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
_fieldlist_row_index
_table_row_index
docclasses	Prepends prefix to sphinx document classes
docname	Returns the docname of the document currently being parsed.
found_docs	contains all existing docnames.
html_themes
math_renderer_name
table	Get current table.

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:
_add_missing_ids
_check_init_
_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
depart_viewcode_anchor
depart_viewcode_anchor
depart_viewcode_anchor
depart_viewcode_anchor
depart_viewcode_anchor
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.
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
visit_viewcode_anchor
visit_viewcode_anchor
visit_viewcode_anchor
visit_viewcode_anchor
visit_viewcode_anchor
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(document, builder, *args, **kwds)

Bases: DocTreeTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

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

constructor

source on GitHub

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

Bases: _WriterWithCustomDirectives, 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(document, builder, *args, **kwds)

Bases: _AdditionalVisitDepart, HTML5Translator

See HTMLWriterWithCustomDirectives.

source on GitHub

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

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: _WriterWithCustomDirectives, 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(document, builder, *args, **kwds)

Bases: _AdditionalVisitDepart, EnhancedLaTeXTranslator

See LatexWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

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

constructor

source on GitHub

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

Bases: _WriterWithCustomDirectives, 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(document, builder, *args, **kwds)

Bases: _AdditionalVisitDepart, MdTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

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

constructor

source on GitHub

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

Bases: _WriterWithCustomDirectives, 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: _MemoryBuilder, 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

format = 'doctree'

The builder’s output format, or ‘’ if no document output is produced.

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

Override handle_page to write into stream instead of files.

source on GitHub

name = 'memorydoctree'

The builder’s name, for the -b command line option.

supported_data_uri_images = True

The builder supports data URIs or not.

supported_remote_images = True

The builder supports remote images or not.

translator_class

alias of DocTreeTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryHTMLBuilder(app)

Bases: _MemoryBuilder, CustomSingleFileHTMLBuilder

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

format = 'html'

The builder’s output format, or ‘’ if no document output is produced.

name = 'memoryhtml'

The builder’s name, for the -b command line option.

out_suffix = None

supported_data_uri_images = True

The builder supports data URIs or not.

supported_image_types: List[str] = ['application/pdf', 'image/png', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

supported_remote_images = True

The builder supports remote images or not.

translator_class

alias of HTMLTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryLatexBuilder(app)

Bases: _MemoryBuilder, 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(initial_value='', newline='\n')

Bases: 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

format = 'tex'

The builder’s output format, or ‘’ if no document output is produced.

name = 'memorylatex'

The builder’s name, for the -b command line option.

supported_data_uri_images = True

The builder supports data URIs or not.

supported_image_types: List[str] = ['image/png', 'image/jpeg', 'image/gif']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

supported_remote_images = True

The builder supports remote images or not.

translator_class

alias of LatexTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryMDBuilder(app)

Bases: _MemoryBuilder, 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

format = 'md'

The builder’s output format, or ‘’ if no document output is produced.

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

Override handle_page to write into stream instead of files.

source on GitHub

name = 'memorymd'

The builder’s name, for the -b command line option.

supported_data_uri_images = True

The builder supports data URIs or not.

supported_image_types: List[str] = ['application/pdf', 'image/png', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

supported_remote_images = True

The builder supports remote images or not.

translator_class

alias of MDTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryRSTBuilder(app)

Bases: _MemoryBuilder, 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

format = 'rst'

The builder’s output format, or ‘’ if no document output is produced.

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

Override handle_page to write into stream instead of files.

source on GitHub

name = 'memoryrst'

The builder’s name, for the -b command line option.

supported_data_uri_images = True

The builder supports data URIs or not.

supported_image_types: List[str] = ['application/pdf', 'image/png', 'image/jpeg']

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

supported_remote_images = True

The builder supports remote images or not.

translator_class

alias of RSTTranslatorWithCustomDirectives

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

Bases: _AdditionalVisitDepart, RstTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

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

constructor

source on GitHub

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

Bases: _WriterWithCustomDirectives, 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.

source on GitHub

__init__(output_format)

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: 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.

source on GitHub

get_doctree(docname)

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

source on GitHub

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

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,
 'hpp': sphinx.domains.cpp.CPPDomain,
 'h': 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,
 'hpp': sphinx.domains.cpp.CPPDomain,
 'h': 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

_add_missing_ids(doctree)

_check_init_()

_extended_init_()

Additional initialization steps.

source on GitHub

_init_env(freshenv)

_lookup_doctree(doctree, node_type)

_warncount: int

add_builder(builder, override=False)

Register a new builder.

Parameters

• builder – A builder class

• override – If true, install the builder forcedly even if another builder is already installed as the same name

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.

Parameters

• name – The name of the configuration value. It is recommended to be prefixed with the extension name (ex. html_logo, epub_title)

• default – The default value of the configuration.

• rebuild –

  The condition of rebuild. It 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.

• types – The type of configuration value. A list of types can be specified. For example, [str] is used to describe a configuration that takes string value.

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.

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.

add_css_file(filename, priority=500, **kwargs)

Register a stylesheet to include in the HTML output.

Parameters

• filename – The filename of the CSS file. It must be relative to the HTML static path, or a full URI with scheme.

• priority – The priority to determine the order of <link> tag for the CSS files. See list of “prority range for CSS files” below. If the priority of the CSS files it the same as others, the CSS files will be loaded in order of registration.

• kwargs – Extra keyword arguments are included as attributes of the <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" />

priority range for CSS files

Priority	Main purpose in Sphinx
200	default priority for built-in CSS files
500	default priority for extensions
800	default priority for :confval:`html_css_files`

A CSS file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event.

New in version 1.0.

Changed in version 1.6: Optional alternate and/or title attributes can be supplied with the arguments alternate (a Boolean) and title (a string). 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.

Changed in version 3.5: Take priority argument. Allow to add a CSS file to the specific page.

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

Register a Docutils directive.

Parameters

• name – The name of the directive

• cls – A directive class

• override – If true, install the directive forcedly even if another directive is already installed as the same name

For example, a custom directive named my-directive would be added like this:

from docutils.parsers.rst import Directive, directives

class MyDirective(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):
        ...

def setup(app):
    app.add_directive('my-directive', MyDirective)

For more details, see the Docutils docs .

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.

Parameters

• domain – The name of target domain

• name – A name of directive

• cls – A directive class

• override – If true, install the directive forcedly even if another directive is already installed as the same name

New in version 1.0.

Changed in version 1.8: Add override keyword.

add_domain(domain, override=True)

Register a domain.

Parameters

• domain – A domain class

• override – If true, install the domain forcedly even if another domain is already installed as the same name

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.

Parameters

name – The name of the event

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.

If override is True, the given nodeclass is forcedly installed even if a role named as name is already installed.

New in version 0.6.

Changed in version 1.8: Add override keyword.

add_js_file(filename, priority=500, **kwargs)

Register a JavaScript file to include in the HTML output.

Parameters

• filename – The filename of the JavaScript file. It must be relative to the HTML static path, a full URI with scheme, or None value. The None value is used to create inline <script> tag. See the description of kwargs below.

• priority – The priority to determine the order of <script> tag for JavaScript files. See list of “prority range for JavaScript files” below. If the priority of the JavaScript files it the same as others, the JavaScript files will be loaded in order of registration.

• loading_method – The loading method of the JavaScript file. 'async' or 'defer' is allowed.

• kwargs – Extra keyword arguments are included as attributes of the <script> tag. A special keyword argument body is given, its value will be added between the <script> tag.

Example:

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

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

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

priority range for JavaScript files

Priority	Main purpose in Sphinx
200	default priority for built-in JavaScript files
500	default priority for extensions
800	default priority for :confval:`html_js_files`

A JavaScript file can be added to the specific HTML page when an extension calls this method on :event:`html-page-context` event.

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.

Changed in version 3.5: Take priority argument. Allow to add a JavaScript file to the specific page.

Changed in version 4.4: Take loading_method argument. Allow to change the loading method of the JavaScript file.

add_latex_package(packagename, options=None, after_hyperref=False)

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 the usepackage declaration. If you set after_hyperref truthy, the package will be loaded after hyperref package.

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

New in version 1.3.

New in version 3.1: after_hyperref option.

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.

Parameters

• node – A node class

• kwargs – Visitor functions for each builder (see below)

• override – If true, install the node forcedly even if another node is already installed as the same name

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).

If override is True, the given object_type is forcedly installed even if an object_type having the same name is already installed.

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.

Parameters

transform – A transform class

add_role(name, role, override=True)

Register a Docutils role.

Parameters

• name – The name of role

• role – A role function

• override – If true, install the role forcedly even if another role is already installed as the same name

For more details about role functions, see the Docutils docs .

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.

Parameters

• domain – The name of the target domain

• name – The name of the role

• role – The role function

• override – If true, install the role forcedly even if another role is already installed as the same name

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.

Parameters

transform – A transform class

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

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