module sphinxext.sphinx_rst_builder

Inheritance diagram of pyquickhelper.sphinxext.sphinx_rst_builder

Short summary

module pyquickhelper.sphinxext.sphinx_rst_builder

Defines a sphinx extension to output the documentation in RST. It is inspired from restbuilder. I replicate its license here:

Copyright (c) 2012-2013 by Freek Dijkstra <software@macfreek.nl>.
Some rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

source on GitHub

Classes

class

truncated documentation

RstBuilder

Defines a RST builder.

RstTranslator

Defines a RST translator.

RstWriter

Defines a RST writer.

Functions

function

truncated documentation

setup

Initializes the RST builder.

Static Methods

staticmethod

truncated documentation

_make_depart_admonition

Methods

method

truncated documentation

__init__

Constructor, add a logger.

__init__

__init__

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

_visit_admonition

add_text

depart_abbreviation

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_admonition

depart_attribution

depart_bigger_node

depart_block_quote

depart_bullet_list

depart_caption

depart_centered

depart_citation

depart_classifier

depart_CodeNode

depart_collapse_node

depart_compact_paragraph

depart_compound

depart_definition

depart_definition_list

depart_definition_list_item

depart_desc

depart_desc_addname

depart_desc_annotation

depart_desc_content

depart_desc_name

depart_desc_optional

depart_desc_parameterlist

depart_desc_returns

depart_desc_signature

depart_desc_type

depart_description

depart_doctest_block

depart_document

depart_download_reference

depart_downloadlink_node

depart_emphasis

depart_entry

depart_enumerated_list

depart_field

depart_field_body

depart_field_list

depart_field_name

depart_figure

depart_footnote

depart_generated

depart_gitlog_node

depart_glossary

depart_hlist

depart_hlistcol

depart_image

depart_inheritance_diagram

depart_inline

depart_issue

depart_line

depart_line_block

depart_list_item

depart_literal

depart_literal_block

depart_literal_emphasis

depart_only

depart_option

depart_option_argument

depart_option_group

depart_option_list

depart_option_list_item

depart_option_string

depart_paragraph

depart_pending_xref

depart_problematic

depart_quote_node

depart_refcount

depart_reference

depart_row

depart_rubric

depart_runpythonthis_node

depart_section

depart_seealso

depart_sharenet_node

depart_simpleimage

depart_strong

depart_subscript

depart_subtitle

depart_superscript

depart_table

depart_target

depart_tbody

depart_term

depart_Text

depart_tgroup

depart_thead

depart_title

depart_title_reference

depart_topic

depart_topic

depart_versionmodified

end_state

eval_expr

finish

get_outdated_docs

Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs()

get_outfilename

Overwrites get_target_uri to control file names.

get_target_uri

handle_page

init

Load necessary templates and perform initialization.

log_unknown

new_state

prepare_writing

translate

unknown_visit

visit_abbreviation

visit_acks

visit_admonition

visit_attribution

visit_bigger_node

visit_block_quote

visit_bullet_list

visit_caption

visit_centered

visit_citation

visit_citation_reference

visit_classifier

visit_CodeNode

visit_collapse_node

visit_colspec

visit_comment

visit_compact_paragraph

visit_compound

visit_definition

visit_definition_list

visit_definition_list_item

visit_desc

visit_desc_addname

visit_desc_annotation

visit_desc_content

visit_desc_name

visit_desc_optional

visit_desc_parameter

visit_desc_parameterlist

visit_desc_returns

visit_desc_signature

visit_desc_type

visit_description

visit_doctest_block

visit_document

visit_download_reference

visit_downloadlink_node

visit_emphasis

visit_entry

visit_enumerated_list

visit_field

visit_field_body

visit_field_list

visit_field_name

visit_figure

visit_footnote

visit_footnote_reference

visit_generated

visit_gitlog_node

visit_glossary

visit_highlightlang

visit_hlist

visit_hlistcol

visit_image

visit_index

visit_inheritance_diagram

visit_inline

visit_issue

visit_label

visit_line

visit_line_block

visit_list_item

visit_literal

visit_literal_block

visit_literal_emphasis

visit_meta

visit_only

visit_option

visit_option_argument

visit_option_group

visit_option_list

visit_option_list_item

visit_option_string

visit_paragraph

visit_pending_xref

visit_problematic

visit_productionlist

visit_quote_node

visit_raw

visit_refcount

visit_reference

Runs upon entering a reference. Because this class inherits from the TextTranslator class, regularly defined …

visit_row

visit_rubric

visit_runpythonthis_node

visit_section

visit_seealso

visit_sharenet_node

visit_simpleimage

visit_strong

visit_subscript

visit_substitution_definition

visit_subtitle

visit_superscript

visit_system_message

visit_table

visit_tabular_col_spec

visit_target

visit_tbody

visit_term

visit_termsep

visit_Text

visit_tgroup

visit_thead

visit_title

visit_title_reference

visit_topic

visit_topic

visit_transition

visit_versionmodified

wrap

write_doc

Documentation

Defines a sphinx extension to output the documentation in RST. It is inspired from restbuilder. I replicate its license here:

Copyright (c) 2012-2013 by Freek Dijkstra <software@macfreek.nl>.
Some rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

source on GitHub

class pyquickhelper.sphinxext.sphinx_rst_builder.RstBuilder(*args, **kwargs)[source][source]

Bases: sphinx.builders.Builder

Defines a RST builder.

source on GitHub

Constructor, add a logger.

source on GitHub

__init__(*args, **kwargs)[source][source]

Constructor, add a logger.

source on GitHub

default_translator_class[source]

alias of RstTranslator

finish()[source][source]

Finish the building process.

The default implementation does nothing.

get_outdated_docs()[source][source]

Return an iterable of input files that are outdated. This method is taken from TextBuilder.get_outdated_docs() with minor changes to support (confval, rst_file_transform)).

source on GitHub

get_outfilename(pagename)[source][source]

Overwrites get_target_uri to control file names.

source on GitHub

get_target_uri(docname, typ=None)[source][source]

Return the target URI for a document name.

typ can be used to qualify the link characteristic for individual builders.

init()[source][source]

Load necessary templates and perform initialization.

source on GitHub

prepare_writing(docnames)[source][source]

A place where you can add logic before write_doc() is run

write_doc(docname, doctree)[source][source]

Where you actually write something to the filesystem.

class pyquickhelper.sphinxext.sphinx_rst_builder.RstTranslator(builder, document)[source][source]

Bases: sphinx.writers.text.TextTranslator, pyquickhelper.sphinxext._sphinx_common_builder.CommonSphinxWriterHelpers

Defines a RST translator.

source on GitHub

__init__(builder, document)[source][source]

Initialize self. See help(type(self)) for accurate signature.

_make_depart_admonition()[source][source]
_visit_admonition(node)[source][source]
depart_bigger_node(node)[source][source]

depart bigger_node for format other than html

source on GitHub

depart_collapse_node(node)[source][source]

depart collapse_node

source on GitHub

Does notthing.

source on GitHub

depart_gitlog_node(node)[source][source]

depart gitlog_node for format other than html

source on GitHub

depart_quote_node(node)[source][source]

depart_quote_node, see https://github.com/sphinx-doc/sphinx/blob/master/sphinx/writers/html.py

source on GitHub

depart_sharenet_node(node)[source][source]

what to do when leaving a node sharenet the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

It does only html for the time being.

source on GitHub

unknown_visit(node)[source][source]

Called when entering unknown Node types.

Raise an exception unless overridden.

visit_bigger_node(node)[source][source]

what to do when visiting a node bigger the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

source on GitHub

visit_collapse_node(node)[source][source]

visit collapse_node

source on GitHub

Does notthing.

source on GitHub

visit_gitlog_node(node)[source][source]

what to do when visiting a node gitlog the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

source on GitHub

visit_quote_node(node)[source][source]

source on GitHub

visit_reference(node)[source][source]

Runs upon entering a reference. Because this class inherits from the TextTranslator class, regularly defined links, such as:

`Some Text`_

.. _Some Text: http://www.some_url.com

were being written as plaintext. This included internal references defined in the standard rst way, such as:

`Some Reference`

.. _Some Reference:

Some Title
----------

To resolve this, if refuri is not included in the node (an internal, non-Sphinx-defined internal uri, the reference is left unchanged.

If internal is not in the node (as for an external, non-Sphinx URI, the reference is rewritten as an inline link, e.g.:

Some Text <http://www.some_url.com>`_

If reftitle is in the node (as in a Sphinx-generated reference), the node is converted to an inline link.

Finally, all other links are also converted to an inline link format.

source on GitHub

visit_sharenet_node(node)[source][source]

what to do when visiting a node sharenet the function should have different behaviour, depending on the format, or the setup should specify a different function for each.

source on GitHub

class pyquickhelper.sphinxext.sphinx_rst_builder.RstWriter(builder)[source][source]

Bases: docutils.writers.Writer

Defines a RST writer.

source on GitHub

__init__(builder)[source][source]

Initialize self. See help(type(self)) for accurate signature.

translate()[source][source]

Do final translation of self.document into self.output. Called from write. Override in subclasses.

Usually done with a docutils.nodes.NodeVisitor subclass, in combination with a call to docutils.nodes.Node.walk() or docutils.nodes.Node.walkabout(). The NodeVisitor subclass must support all standard elements (listed in docutils.nodes.node_class_names) and possibly non-standard elements used by the current Reader as well.

translator_class[source]

alias of RstTranslator

pyquickhelper.sphinxext.sphinx_rst_builder.setup(app)[source][source]

Initializes the RST builder.

source on GitHub