module helpgen.sphinxm_convert_doc_sphinx_helper

Short summary

module pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper

Helpers to convert docstring to various format.

source on GitHub

Classes

class	truncated documentation
_AdditionalVisitDepart	Additional visitors and departors.
_CustomBuildEnvironment	Overrides some functionalities of BuildEnvironment.
_CustomSphinx	Custom Sphinx application to avoid using disk.
_MemoryBuilder	Builds HTML output in memory. The API is defined by the page builderapi.
_WriterWithCustomDirectives	Common class to HTMLWriterWithCustomDirectives and RSTWriterWithCustomDirectives.
DocTreeTranslatorWithCustomDirectives	See HTMLWriterWithCustomDirectives.
DocTreeWriterWithCustomDirectives	This docutils writer creates a doctree writer with custom directives implemented in this module.
HTMLTranslatorWithCustomDirectives	See HTMLWriterWithCustomDirectives.
HTMLWriterWithCustomDirectives	This docutils writer extends the HTML writer with custom directives implemented in this module, RunPythonDirective, …
LatexTranslatorWithCustomDirectives	See LatexWriterWithCustomDirectives.
LatexWriterWithCustomDirectives	This docutils writer extends the Latex writer with custom directives implemented in this module.
MDTranslatorWithCustomDirectives	See HTMLWriterWithCustomDirectives.
MDWriterWithCustomDirectives	This docutils writer extends the MD writer with custom directives implemented in this module.
MemoryDocTreeBuilder	Builds doctree output in memory. The API is defined by the page builderapi.
MemoryHTMLBuilder	Builds HTML output in memory. The API is defined by the page builderapi.
MemoryLatexBuilder	Builds Latex output in memory. The API is defined by the page builderapi.
MemoryMDBuilder	Builds MD output in memory. The API is defined by the page builderapi.
MemoryRSTBuilder	Builds RST output in memory. The API is defined by the page builderapi. The writer simplifies …
RSTTranslatorWithCustomDirectives	See HTMLWriterWithCustomDirectives.
RSTWriterWithCustomDirectives	This docutils writer extends the RST writer with custom directives implemented in this module.

Functions

function	truncated documentation
_get_LaTeXTranslator
update_docutils_languages	Updates docutils/languages/en.py with missing labels. It Does it for languages en.

Properties

property	truncated documentation
_nitpick_ignore
_setting_up_extension
bibitems
docname	Returns the docname of the document currently being parsed.
enumerable_nodes
footnotestack
found_docs	contains all existing docnames.
highlightlang
highlightlang_base
highlightlinenothreshold
highlightopts
hlsettingstack
in_container_literal_block
math_renderer_name
next_hyperlink_ids
next_section_ids
versionchanges

Methods

method	truncated documentation
__init__	constructor
__init__
__init__
__init__
__init__	constructor
__init__
__init__	constructor
__init__
__init__	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
__init__	Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). …
__init__	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
__init__	Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). …
__init__	Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). …
__init__	constructor
__init__
__init__
__init__
__init__	Same constructor as Sphinx application. Additional parameters:
_extended_init_	Additional initialization steps.
_get_filename
_init
_init
_init
_init
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init
_init	Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten …
_init
_init_env
_lookup_doctree
_write_parallel	Not supported.
_write_parallel	Not supported.
_write_parallel	Not supported.
_write_parallel	Not supported.
_write_parallel	Not supported.
_write_parallel	Not supported.
_write_serial	Overwrites _write_serial to avoid writing on disk.
_write_serial	Overwrites _write_serial to avoid writing on disk.
_write_serial	Overwrites _write_serial to avoid writing on disk.
_write_serial	Overwrites _write_serial to avoid writing on disk.
_write_serial	Overwrites _write_serial to avoid writing on disk.
_write_serial	Overwrites _write_serial to avoid writing on disk.
add_builder
add_config_value
add_configuration_options	Add new options.
add_configuration_options	Add new options.
add_configuration_options	Add new options.
add_configuration_options	Add new options.
add_configuration_options	Add new options.
add_configuration_options	Add new options.
add_css_file
add_directive
add_directive_to_domain
add_domain
add_env_collector	See class Sphinx.
add_event
add_generic_role
add_js_file
add_latex_package
add_node
add_object_type
add_post_transform
add_role
add_role_to_domain
add_secnumber	Overwrites this method to catch errors due when it is a single document being processed.
add_secnumber	Overwrites this method to catch errors due when it is a single document being processed.
add_secnumber	Overwrites this method to catch errors due when it is a single document being processed.
add_secnumber	Overwrites this method to catch errors due when it is a single document being processed.
add_secnumber	Overwrites this method to catch errors due when it is a single document being processed.
add_transform
apply_post_transforms	Apply all post-transforms.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
assemble_doctree	Overwrites assemble_doctree to control the doctree.
connect_directive_node	Adds custom node to the translator.
connect_directive_node	Adds custom node to the translator.
connect_directive_node	Adds custom node to the translator.
connect_directive_node	Adds custom node to the translator.
connect_directive_node	Adds custom node to the translator.
connect_directive_node	Adds custom node to the translator.
create_builder	Creates a builder, raises an exception if name is None.
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
create_translator	Returns an instance of translator. This method returns an instance of default_translator_class by default. …
debug
depart_only
depart_only
depart_only
depart_only
depart_only
disconnect_env_collector	Disables a collector given its class name.
eval_expr
eval_expr
eval_expr
eval_expr
eval_expr
finalize	Finalizes the documentation after it was parsed.
fix_refuris	Overwrites fix_refuris to control the reference names.
fix_refuris	Overwrites fix_refuris to control the reference names.
fix_refuris	Overwrites fix_refuris to control the reference names.
fix_refuris	Overwrites fix_refuris to control the reference names.
fix_refuris	Overwrites fix_refuris to control the reference names.
fix_refuris	Overwrites fix_refuris to control the reference names.
get_doctree	Read the doctree for a file from the pickle and return it.
get_outfilename	Overwrites get_target_uri to control file names.
get_outfilename	Overwrites get_target_uri to control file names.
get_outfilename	Overwrites get_target_uri to control file names.
get_outfilename	Overwrites get_target_uri to control file names.
get_outfilename	Overwrites get_target_uri to control file names.
get_outfilename	Overwrites get_target_uri to control file names.
get_target_uri	Overwrites get_target_uri to control the page name.
get_target_uri	Overwrites get_target_uri to control the page name.
get_target_uri	Overwrites get_target_uri to control the page name.
get_target_uri	Overwrites get_target_uri to control the page name.
get_target_uri	Overwrites get_target_uri to control the page name.
get_target_uri	Overwrites get_target_uri to control the page name.
handle_page	Override handle_page to write into stream instead of files.
handle_page	Overrides handle_page to write into stream instead of files.
handle_page	Overrides handle_page to write into stream instead of files.
handle_page	Override handle_page to write into stream instead of files.
handle_page	Override handle_page to write into stream instead of files.
handle_page	Overrides handle_page to write into stream instead of files.
info
is_doctree	Tells if the translator is doctree format.
is_doctree	Tells if the translator is doctree format.
is_doctree	Tells if the translator is doctree format.
is_doctree	Tells if the translator is doctree format.
is_doctree	Tells if the translator is doctree format.
is_html	Tells if the translator is html format.
is_html	Tells if the translator is html format.
is_html	Tells if the translator is html format.
is_html	Tells if the translator is html format.
is_html	Tells if the translator is html format.
is_latex	Tells if the translator is latex format.
is_latex	Tells if the translator is latex format.
is_latex	Tells if the translator is latex format.
is_latex	Tells if the translator is latex format.
is_latex	Tells if the translator is latex format.
is_md	Tells if the translator is markdown format.
is_md	Tells if the translator is markdown format.
is_md	Tells if the translator is markdown format.
is_md	Tells if the translator is markdown format.
is_md	Tells if the translator is markdown format.
is_rst	Tells if the translator is rst format.
is_rst	Tells if the translator is rst format.
is_rst	Tells if the translator is rst format.
is_rst	Tells if the translator is rst format.
is_rst	Tells if the translator is rst format.
iter_pages	Enumerate created pages.
iter_pages	Enumerate created pages.
iter_pages	Enumerate created pages.
iter_pages	Enumerate created pages.
iter_pages	Enumerate created pages.
iter_pages	Enumerate created pages.
override_domain
setup_extension
translate
translate
translate
translate
translate
unknown_visit
unknown_visit
unknown_visit
unknown_visit
unknown_visit
visit_field
visit_only
visit_only
visit_only
visit_only
visit_only
visit_pending_xref
warning
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write	Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s …
write_stylesheet

Documentation

Helpers to convert docstring to various format.

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeTranslatorWithCustomDirectives(builder, *args, **kwds)

Bases: pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

__init__(builder, *args, **kwds)

constructor

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeWriterWithCustomDirectives(builder=None, app=None)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives, pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeWriter

This docutils writer creates a doctree writer with custom directives implemented in this module.

source on GitHub

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

__init__(builder=None, app=None)

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

translate()

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLTranslatorWithCustomDirectives(builder, *args, **kwds)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart, sphinx.writers.html5.HTML5Translator

See HTMLWriterWithCustomDirectives.

source on GitHub

Changed in version 1.7: Does something specific for HTML. only is a node.

source on GitHub

__init__(builder, *args, **kwds)

Changed in version 1.7: Does something specific for HTML. only is a node.

source on GitHub

unknown_visit(node)

Called when entering unknown Node types.

Raise an exception unless overridden.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLWriterWithCustomDirectives(builder=None, app=None)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives, sphinx.writers.html.HTMLWriter

This docutils writer extends the HTML writer with custom directives implemented in this module, RunPythonDirective, BlogPostDirective.

See Write your own ReStructuredText-Writer.

This class needs to tell docutils to call the added function when directives runpython or blogpost are met.

source on GitHub

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

__init__(builder=None, app=None)

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

translate()

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexTranslatorWithCustomDirectives(builder, document, *args, **kwds)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart, pyquickhelper.sphinxext.sphinx_latex_builder.EnhancedLaTeXTranslator

See LatexWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

__init__(builder, document, *args, **kwds)

constructor

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexWriterWithCustomDirectives(builder=None, app=None)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives, pyquickhelper.sphinxext.sphinx_latex_builder.EnhancedLaTeXWriter

This docutils writer extends the Latex writer with custom directives implemented in this module.

source on GitHub

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

__init__(builder=None, app=None)

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

translate()

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDTranslatorWithCustomDirectives(builder, *args, **kwds)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart, pyquickhelper.sphinxext.sphinx_md_builder.MdTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

__init__(builder, *args, **kwds)

constructor

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDWriterWithCustomDirectives(builder=None, app=None)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives, pyquickhelper.sphinxext.sphinx_md_builder.MdWriter

This docutils writer extends the MD writer with custom directives implemented in this module.

source on GitHub

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

__init__(builder=None, app=None)

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

translate()

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryDocTreeBuilder(app)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder, pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeBuilder

Builds doctree output in memory. The API is defined by the page builderapi.

source on GitHub

Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

__init__(app)

Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

_writer_class

alias of DocTreeWriterWithCustomDirectives

default_translator_class

alias of DocTreeTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)

Override handle_page to write into stream instead of files.

source on GitHub

translator_class

alias of DocTreeTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryHTMLBuilder(app)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder, sphinx.builders.singlehtml.SingleFileHTMLBuilder

Builds HTML output in memory. The API is defined by the page builderapi.

source on GitHub

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

__init__(app)

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

_writer_class

alias of HTMLWriterWithCustomDirectives

default_translator_class

alias of HTMLTranslatorWithCustomDirectives

translator_class

alias of HTMLTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryLatexBuilder(app)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder, pyquickhelper.sphinxext.sphinx_latex_builder.EnhancedLaTeXBuilder

Builds Latex output in memory. The API is defined by the page builderapi.

source on GitHub

Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

class EnhancedStringIO

Bases: _io.StringIO

write(content)

Write string to file.

Returns the number of characters written, which is always equal to the length of the string.

__init__(app)

Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

_get_filename(targetname, encoding='utf-8', overwrite_if_changed=True)

_writer_class

alias of LatexWriterWithCustomDirectives

default_translator_class

alias of LatexTranslatorWithCustomDirectives

translator_class

alias of LatexTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryMDBuilder(app)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder, pyquickhelper.sphinxext.sphinx_md_builder.MdBuilder

Builds MD output in memory. The API is defined by the page builderapi.

source on GitHub

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

__init__(app)

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

_writer_class

alias of MDWriterWithCustomDirectives

default_translator_class

alias of MDTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)

Override handle_page to write into stream instead of files.

source on GitHub

translator_class

alias of MDTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryRSTBuilder(app)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder, pyquickhelper.sphinxext.sphinx_rst_builder.RstBuilder

Builds RST output in memory. The API is defined by the page builderapi. The writer simplifies the RST syntax by replacing custom roles into true RST syntax.

source on GitHub

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

__init__(app)

Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

app – Sphinx application

source on GitHub

_writer_class

alias of RSTWriterWithCustomDirectives

default_translator_class

alias of RSTTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)

Override handle_page to write into stream instead of files.

source on GitHub

translator_class

alias of RSTTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTTranslatorWithCustomDirectives(builder, *args, **kwds)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart, pyquickhelper.sphinxext.sphinx_rst_builder.RstTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

__init__(builder, *args, **kwds)

constructor

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTWriterWithCustomDirectives(builder=None, app=None)

Bases: pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives, pyquickhelper.sphinxext.sphinx_rst_builder.RstWriter

This docutils writer extends the RST writer with custom directives implemented in this module.

source on GitHub

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

__init__(builder=None, app=None)

Parameters

• builder – builder

• app – Sphinx application

source on GitHub

translate()

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart(output_format)

Bases: object

Additional visitors and departors.

Changed in version 1.7: Update for Sphinx 1.7.

source on GitHub

New in version 1.7.

source on GitHub

__init__(output_format)

New in version 1.7.

source on GitHub

add_secnumber(node)

Overwrites this method to catch errors due when it is a single document being processed.

source on GitHub

is_doctree()

Tells if the translator is doctree format.

source on GitHub

is_html()

Tells if the translator is html format.

source on GitHub

is_latex()

Tells if the translator is latex format.

source on GitHub

is_md()

Tells if the translator is markdown format.

source on GitHub

is_rst()

Tells if the translator is rst format.

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._CustomBuildEnvironment(app)

Bases: sphinx.environment.BuildEnvironment

Overrides some functionalities of BuildEnvironment.

source on GitHub

source on GitHub

__init__(app)

source on GitHub

apply_post_transforms(doctree, docname)

Apply all post-transforms.

get_doctree(docname)

Read the doctree for a file from the pickle and return it.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._CustomSphinx(srcdir, confdir, outdir, doctreedir, buildername='memoryhtml', confoverrides=None, status=None, warning=None, freshenv=False, warningiserror=False, tags=None, verbosity=0, parallel=0, keep_going=False, new_extensions=None)

Bases: sphinx.application.Sphinx

Custom Sphinx application to avoid using disk.

source on GitHub

Same constructor as Sphinx application. Additional parameters:

Parameters

new_extensions – extensions to add to the application

Some insights about domains:

{'cpp': sphinx.domains.cpp.CPPDomain,
 'js': sphinx.domains.javascript.JavaScriptDomain,
 'std': sphinx.domains.std.StandardDomain,
 'py': sphinx.domains.python.PythonDomain,
 'rst': sphinx.domains.rst.ReSTDomain,
 'c': sphinx.domains.c.CDomain}

And builders:

{'epub': ('epub', 'EpubBuilder'),
'singlehtml': ('html', 'SingleFileHTMLBuilder'),
'qthelp': ('qthelp', 'QtHelpBuilder'),
'epub3': ('epub3', 'Epub3Builder'),
'man': ('manpage', 'ManualPageBuilder'),
'dummy': ('dummy', 'DummyBuilder'),
'json': ('html', 'JSONHTMLBuilder'),
'html': ('html', 'StandaloneHTMLBuilder'),
'xml': ('xml', 'XMLBuilder'),
'texinfo': ('texinfo', 'TexinfoBuilder'),
'devhelp': ('devhelp', 'DevhelpBuilder'),
'web': ('html', 'PickleHTMLBuilder'),
'pickle': ('html', 'PickleHTMLBuilder'),
'htmlhelp': ('htmlhelp', 'HTMLHelpBuilder'),
'applehelp': ('applehelp', 'AppleHelpBuilder'),
'linkcheck': ('linkcheck', 'CheckExternalLinksBuilder'),
'dirhtml': ('html', 'DirectoryHTMLBuilder'),
'latex': ('latex', 'LaTeXBuilder'),
'elatex': ('latex', 'EnchancedLaTeXBuilder'),
'text': ('text', 'TextBuilder'),
'changes': ('changes', 'ChangesBuilder'),
'websupport': ('websupport', 'WebSupportBuilder'),
'gettext': ('gettext', 'MessageCatalogBuilder'),
'pseudoxml': ('xml', 'PseudoXMLBuilder')}
'rst': ('rst', 'RstBuilder')}
'md': ('md', 'MdBuilder'),
'doctree': ('doctree', 'DocTreeBuilder')}

source on GitHub

__init__(srcdir, confdir, outdir, doctreedir, buildername='memoryhtml', confoverrides=None, status=None, warning=None, freshenv=False, warningiserror=False, tags=None, verbosity=0, parallel=0, keep_going=False, new_extensions=None)

Same constructor as Sphinx application. Additional parameters:

Parameters

new_extensions – extensions to add to the application

Some insights about domains:

{'cpp': sphinx.domains.cpp.CPPDomain,
 'js': sphinx.domains.javascript.JavaScriptDomain,
 'std': sphinx.domains.std.StandardDomain,
 'py': sphinx.domains.python.PythonDomain,
 'rst': sphinx.domains.rst.ReSTDomain,
 'c': sphinx.domains.c.CDomain}

And builders:

{'epub': ('epub', 'EpubBuilder'),
'singlehtml': ('html', 'SingleFileHTMLBuilder'),
'qthelp': ('qthelp', 'QtHelpBuilder'),
'epub3': ('epub3', 'Epub3Builder'),
'man': ('manpage', 'ManualPageBuilder'),
'dummy': ('dummy', 'DummyBuilder'),
'json': ('html', 'JSONHTMLBuilder'),
'html': ('html', 'StandaloneHTMLBuilder'),
'xml': ('xml', 'XMLBuilder'),
'texinfo': ('texinfo', 'TexinfoBuilder'),
'devhelp': ('devhelp', 'DevhelpBuilder'),
'web': ('html', 'PickleHTMLBuilder'),
'pickle': ('html', 'PickleHTMLBuilder'),
'htmlhelp': ('htmlhelp', 'HTMLHelpBuilder'),
'applehelp': ('applehelp', 'AppleHelpBuilder'),
'linkcheck': ('linkcheck', 'CheckExternalLinksBuilder'),
'dirhtml': ('html', 'DirectoryHTMLBuilder'),
'latex': ('latex', 'LaTeXBuilder'),
'elatex': ('latex', 'EnchancedLaTeXBuilder'),
'text': ('text', 'TextBuilder'),
'changes': ('changes', 'ChangesBuilder'),
'websupport': ('websupport', 'WebSupportBuilder'),
'gettext': ('gettext', 'MessageCatalogBuilder'),
'pseudoxml': ('xml', 'PseudoXMLBuilder')}
'rst': ('rst', 'RstBuilder')}
'md': ('md', 'MdBuilder'),
'doctree': ('doctree', 'DocTreeBuilder')}

source on GitHub

_extended_init_()

Additional initialization steps.

source on GitHub

_init_env(freshenv)

_lookup_doctree(doctree, node_type)

add_builder(builder, override=False)

Register a new builder.

builder must be a class that inherits from Builder.

Changed in version 1.8: Add override keyword.

add_config_value(name, default, rebuild, types_=())

Register a configuration value.

This is necessary for Sphinx to recognize new values and set default values accordingly. The name should be prefixed with the extension name, to avoid clashes. The default value can be any Python object. The string value rebuild must be one of those values:

• 'env' if a change in the setting only takes effect when a document is parsed – this means that the whole environment must be rebuilt.

• 'html' if a change in the setting needs a full rebuild of HTML documents.

• '' if a change in the setting will not need any special rebuild.

Changed in version 0.6: Changed rebuild from a simple boolean (equivalent to '' or 'env') to a string. However, booleans are still accepted and converted internally.

Changed in version 0.4: If the default value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values.

add_css_file(filename, **kwargs)

Register a stylesheet to include in the HTML output.

Add filename to the list of CSS files that the default HTML template will include. The filename must be relative to the HTML static path, or a full URI with scheme. The keyword arguments are also accepted for attributes of <link> tag.

Example:

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

New in version 1.0.

Changed in version 1.6: Optional alternate and/or title attributes can be supplied with the alternate (of boolean type) and title (a string) arguments. The default is no title and alternate = False. For more information, refer to the documentation.

Changed in version 1.8: Renamed from app.add_stylesheet(). And it allows keyword arguments as attributes of link tag.

add_directive(name, obj, content=None, arguments=None, override=True, **options)

Register a Docutils directive.

name must be the prospective directive name. There are two possible ways to write a directive:

• In the docutils 0.4 style, obj is the directive function. content, arguments and options are set as attributes on the function and determine whether the directive has content, arguments and options, respectively. This style is deprecated.

• In the docutils 0.5 style, obj is the directive class. It must already have attributes named has_content, required_arguments, optional_arguments, final_argument_whitespace and option_spec that correspond to the options for the function way. See the Docutils docs for details.

The directive class must inherit from the class docutils.parsers.rst.Directive.

For example, the (already existing) literalinclude directive would be added like this:

from docutils.parsers.rst import Directive, directives

class LiteralIncludeDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        ...

add_directive('literalinclude', LiteralIncludeDirective)

Changed in version 0.6: Docutils 0.5-style directive classes are now supported.

Deprecated since version 1.8: Docutils 0.4-style (function based) directives support is deprecated.

Changed in version 1.8: Add override keyword.

add_directive_to_domain(domain, name, obj, has_content=None, argument_spec=None, override=False, **option_spec)

Register a Docutils directive in a domain.

Like add_directive(), but the directive is added to the domain named domain.

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_domain(domain, override=True)

Register a domain.

Make the given domain (which must be a class; more precisely, a subclass of Domain) known to Sphinx.

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_env_collector(collector)

See class Sphinx.

source on GitHub

add_event(name)

Register an event called name.

This is needed to be able to emit it.

add_generic_role(name, nodeclass, override=True)

Register a generic Docutils role.

Register a Docutils role that does nothing but wrap its contents in the node given by nodeclass.

New in version 0.6.

Changed in version 1.8: Add override keyword.

add_js_file(filename, **kwargs)

Register a JavaScript file to include in the HTML output.

Add filename to the list of JavaScript files that the default HTML template will include. The filename must be relative to the HTML static path , or a full URI with scheme. The keyword arguments are also accepted for attributes of <script> tag.

Example:

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', async="async")
# => <script src="_static/example.js" async="async"></script>

New in version 0.5.

Changed in version 1.8: Renamed from app.add_javascript(). And it allows keyword arguments as attributes of script tag.

add_latex_package(packagename, options=None)

Register a package to include in the LaTeX source code.

Add packagename to the list of packages that LaTeX source code will include. If you provide options, it will be taken to usepackage declaration.

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

New in version 1.3.

add_node(node, override=True, **kwds)

Register a Docutils node class.

This is necessary for Docutils internals. It may also be used in the future to validate nodes in the parsed documents.

Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers can be given as keyword arguments: the keyword should be one or more of 'html', 'latex', 'text', 'man', 'texinfo' or any other supported translators, the value a 2-tuple of (visit, depart) methods. depart can be None if the visit function raises docutils.nodes.SkipNode. Example:

class math(docutils.nodes.Element): pass

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))
def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

Obviously, translators for which you don’t specify visitor methods will choke on the node when encountered in a document to translate.

Changed in version 0.5: Added the support for keyword arguments giving visit functions.

add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=None, override=False)

Register a new object type.

This method is a very convenient way to add a new object type that can be cross-referenced. It will do this:

• Create a new directive (called directivename) for documenting an object. It will automatically add index entries if indextemplate is nonempty; if given, it must contain exactly one instance of %s. See the example below for how the template will be interpreted.

• Create a new role (called rolename) to cross-reference to these object descriptions.

• If you provide parse_node, it must be a function that takes a string and a docutils node, and it must populate the node with children parsed from the string. It must then return the name of the item to be used in cross-referencing and index entries. See the conf.py file in the source for this documentation for an example.

• The objname (if not given, will default to directivename) names the type of object. It is used when listing objects, e.g. in search results.

For example, if you have this call in a custom Sphinx extension:

app.add_object_type('directive', 'dir', 'pair: %s; directive')

you can use this markup in your documents:

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

For the directive, an index entry will be generated as if you had prepended

.. index:: pair: function; directive

The reference node will be of class literal (so it will be rendered in a proportional font, as appropriate for code) unless you give the ref_nodeclass argument, which must be a docutils node class. Most useful are docutils.nodes.emphasis or docutils.nodes.strong – you can also use docutils.nodes.generated if you want no further text decoration. If the text should be treated as literal (e.g. no smart quote replacement), but not have typewriter styling, use sphinx.addnodes.literal_emphasis or sphinx.addnodes.literal_strong.

For the role content, you have the same syntactical possibilities as for standard Sphinx roles (see xref-syntax).

Changed in version 1.8: Add override keyword.

add_post_transform(transform)

Register a Docutils transform to be applied before writing.

Add the standard docutils Transform subclass transform to the list of transforms that are applied before Sphinx writes a document.

add_role(name, role, override=True)

Register a Docutils role.

name must be the role name that occurs in the source, role the role function. Refer to the Docutils documentation for more information.

Changed in version 1.8: Add override keyword.

add_role_to_domain(domain, name, role, override=False)

Register a Docutils role in a domain.

Like add_role(), but the role is added to the domain named domain.

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_transform(transform)

Register a Docutils transform to be applied after parsing.

Add the standard docutils Transform subclass transform to the list of transforms that are applied after Sphinx parses a reST document.

priority range categories for Sphinx transforms

Priority	Main purpose in Sphinx
0-99	Fix invalid nodes by docutils. Translate a doctree.
100-299	Preparation
300-399	early
400-699	main
700-799	Post processing. Deadline to modify text and referencing.
800-899	Collect referencing and referenced nodes. Domain processing.
900-999	Finalize and clean up.

refs: Transform Priority Range Categories

create_builder(name)

Creates a builder, raises an exception if name is None.

source on GitHub

disconnect_env_collector(clname, exc=True)

Disables a collector given its class name.

Parameters

• cl – name

• exc – raises an exception if not found

Returns

found collector

source on GitHub

finalize(doctree, external_docnames=None)

Finalizes the documentation after it was parsed.

Parameters

• doctree – doctree (or pub.document), available after publication

• external_docnames – other docnames the doctree references

source on GitHub

override_domain(domain)

Override a registered domain.

Make the given domain class known to Sphinx, assuming that there is already a domain with its .name. The new domain must be a subclass of the existing one.

New in version 1.0.

Deprecated since version 1.8: Integrated to add_domain().

setup_extension(extname)

Import and setup a Sphinx extension module.

Load the extension given by the module name. Use this if your extension needs the features provided by another extension. No-op if called twice.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder

Bases: object

Builds HTML output in memory. The API is defined by the page builderapi.

source on GitHub

_init(base_class, app)

Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).

Parameters

• base_class – base builder class

• app – Sphinx application

source on GitHub

_write_parallel(docnames, nproc)

Not supported.

source on GitHub

_write_serial(docnames)

Overwrites _write_serial to avoid writing on disk.

source on GitHub

assemble_doctree(*args, **kwargs)

Overwrites assemble_doctree to control the doctree.

source on GitHub

create_translator(*args)

Returns an instance of translator. This method returns an instance of default_translator_class by default. Users can replace the translator class with app.set_translator() API.

source on GitHub

fix_refuris(tree)

Overwrites fix_refuris to control the reference names.

source on GitHub

get_outfilename(pagename)

Overwrites get_target_uri to control file names.

source on GitHub

get_target_uri(docname, typ=None)

Overwrites get_target_uri to control the page name.

source on GitHub

handle_page(pagename, addctx, templatename='page.html', outfilename=None, event_arg=None)

Overrides handle_page to write into stream instead of files.

source on GitHub

iter_pages()

Enumerate created pages.

Returns

iterator on tuple(name, content)

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives

Bases: object

Common class to HTMLWriterWithCustomDirectives and RSTWriterWithCustomDirectives.

source on GitHub

_init(base_class, translator_class, app=None)

Parameters

• base_class – base class

• app – Sphinx application

source on GitHub

add_configuration_options(new_options)

Add new options.

Parameters

new_options – new options

source on GitHub

connect_directive_node(name, f_visit, f_depart)

Adds custom node to the translator.

Parameters

• name – name of the directive

• f_visit – visit function

• f_depart – depart function

source on GitHub

write(document, destination)

Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s native format, and write it out to its destination (a docutils.io.Output subclass object).

Normally not overridden or extended in subclasses.

source on GitHub

pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._get_LaTeXTranslator()

pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.update_docutils_languages(values=None)

Updates docutils/languages/en.py with missing labels. It Does it for languages en.

Parameters

values – consider values in this dictionaries first

source on GitHub