module helpgen.sphinxm_convert_doc_sphinx_helper

Inheritance diagram of pyquickhelper.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)[source][source]

Bases: pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeTranslator

See HTMLWriterWithCustomDirectives.

source on GitHub

constructor

source on GitHub

__init__(builder, *args, **kwds)[source][source]

constructor

source on GitHub

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

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)[source][source]
Parameters
  • builder – builder

  • app – Sphinx application

source on GitHub

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.

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

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)[source][source]

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

source on GitHub

unknown_visit(node)[source][source]

Called when entering unknown Node types.

Raise an exception unless overridden.

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

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)[source][source]
Parameters
  • builder – builder

  • app – Sphinx application

source on GitHub

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.

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

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)[source][source]

constructor

source on GitHub

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

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)[source][source]
Parameters
  • builder – builder

  • app – Sphinx application

source on GitHub

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.

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

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)[source][source]

constructor

source on GitHub

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

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)[source][source]
Parameters
  • builder – builder

  • app – Sphinx application

source on GitHub

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryDocTreeBuilder(app)[source][source]

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

appSphinx application

source on GitHub

__init__(app)[source][source]

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

Parameters

appSphinx application

source on GitHub

_writer_class[source]

alias of DocTreeWriterWithCustomDirectives

default_translator_class[source]

alias of DocTreeTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source][source]

Override handle_page to write into stream instead of files.

source on GitHub

translator_class[source]

alias of DocTreeTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryHTMLBuilder(app)[source][source]

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

appSphinx application

source on GitHub

__init__(app)[source][source]

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

Parameters

appSphinx application

source on GitHub

_writer_class[source]

alias of HTMLWriterWithCustomDirectives

default_translator_class[source]

alias of HTMLTranslatorWithCustomDirectives

translator_class[source]

alias of HTMLTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryLatexBuilder(app)[source][source]

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

appSphinx application

source on GitHub

class EnhancedStringIO[source][source]

Bases: _io.StringIO

write(content)[source][source]

Write string to file.

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

__init__(app)[source][source]

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

Parameters

appSphinx application

source on GitHub

_get_filename(targetname, encoding='utf-8', overwrite_if_changed=True)[source][source]
_writer_class[source]

alias of LatexWriterWithCustomDirectives

default_translator_class[source]

alias of LatexTranslatorWithCustomDirectives

translator_class[source]

alias of LatexTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryMDBuilder(app)[source][source]

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

appSphinx application

source on GitHub

__init__(app)[source][source]

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

Parameters

appSphinx application

source on GitHub

_writer_class[source]

alias of MDWriterWithCustomDirectives

default_translator_class[source]

alias of MDTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source][source]

Override handle_page to write into stream instead of files.

source on GitHub

translator_class[source]

alias of MDTranslatorWithCustomDirectives

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryRSTBuilder(app)[source][source]

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

appSphinx application

source on GitHub

__init__(app)[source][source]

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

Parameters

appSphinx application

source on GitHub

_writer_class[source]

alias of RSTWriterWithCustomDirectives

default_translator_class[source]

alias of RSTTranslatorWithCustomDirectives

handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source][source]

Override handle_page to write into stream instead of files.

source on GitHub

translator_class[source]

alias of RSTTranslatorWithCustomDirectives

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

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)[source][source]

constructor

source on GitHub

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

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)[source][source]
Parameters
  • builder – builder

  • app – Sphinx application

source on GitHub

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.

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart(output_format)[source][source]

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)[source][source]

New in version 1.7.

source on GitHub

add_secnumber(node)[source][source]

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

source on GitHub

is_doctree()[source][source]

Tells if the translator is doctree format.

source on GitHub

is_html()[source][source]

Tells if the translator is html format.

source on GitHub

is_latex()[source][source]

Tells if the translator is latex format.

source on GitHub

is_md()[source][source]

Tells if the translator is markdown format.

source on GitHub

is_rst()[source][source]

Tells if the translator is rst format.

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._CustomBuildEnvironment(app)[source][source]

Bases: sphinx.environment.BuildEnvironment

Overrides some functionalities of BuildEnvironment.

source on GitHub

source on GitHub

__init__(app)[source][source]

source on GitHub

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

Apply all post-transforms.

get_doctree(docname)[source][source]

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)[source][source]

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)[source][source]

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_()[source][source]

Additional initialization steps.

source on GitHub

_init_env(freshenv)[source][source]
_lookup_doctree(doctree, node_type)[source][source]
add_builder(builder, override=False)[source][source]

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_=())[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

See class Sphinx.

source on GitHub

add_event(name)[source][source]

Register an event called name.

This is needed to be able to emit it.

add_generic_role(name, nodeclass, override=True)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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

source on GitHub

disconnect_env_collector(clname, exc=True)[source][source]

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)[source][source]

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)[source][source]

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)[source][source]

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[source][source]

Bases: object

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

source on GitHub

_init(base_class, app)[source][source]

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

Parameters

source on GitHub

_write_parallel(docnames, nproc)[source][source]

Not supported.

source on GitHub

_write_serial(docnames)[source][source]

Overwrites _write_serial to avoid writing on disk.

source on GitHub

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

Overwrites assemble_doctree to control the doctree.

source on GitHub

create_translator(*args)[source][source]

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)[source][source]

Overwrites fix_refuris to control the reference names.

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]

Overwrites get_target_uri to control the page name.

source on GitHub

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

Overrides handle_page to write into stream instead of files.

source on GitHub

iter_pages()[source][source]

Enumerate created pages.

Returns

iterator on tuple(name, content)

source on GitHub

class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._WriterWithCustomDirectives[source][source]

Bases: object

Common class to HTMLWriterWithCustomDirectives and RSTWriterWithCustomDirectives.

source on GitHub

_init(base_class, translator_class, app=None)[source][source]
Parameters
  • base_class – base class

  • app – Sphinx application

source on GitHub

add_configuration_options(new_options)[source][source]

Add new options.

Parameters

new_options – new options

source on GitHub

connect_directive_node(name, f_visit, f_depart)[source][source]

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)[source][source]

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()[source][source]
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.update_docutils_languages(values=None)[source][source]

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