module helpgen.sphinxm_convert_doc_sphinx_helper
¶
Short summary¶
module pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper
Helpers to convert docstring to various format.
Classes¶
class |
truncated documentation |
---|---|
Additional visitors and departors. |
|
Overrides some functionalities of BuildEnvironment. |
|
Custom Sphinx application to avoid using disk. |
|
Builds HTML output in memory. The API is defined by the page builderapi. |
|
Common class to |
|
See |
|
This docutils writer creates a doctree writer with custom directives implemented in this module. |
|
See |
|
This docutils writer extends the HTML writer with custom directives implemented in this module, |
|
See |
|
This docutils writer extends the Latex writer with custom directives implemented in this module. |
|
See |
|
This docutils writer extends the MD writer with custom directives implemented in this module. |
|
Builds doctree output in memory. The API is defined by the page builderapi. |
|
Builds HTML output in memory. The API is defined by the page builderapi. |
|
Builds Latex output in memory. The API is defined by the page builderapi. |
|
Builds MD output in memory. The API is defined by the page builderapi. |
|
Builds RST output in memory. The API is defined by the page builderapi. The writer simplifies … |
|
See |
|
This docutils writer extends the RST writer with custom directives implemented in this module. |
Functions¶
function |
truncated documentation |
---|---|
Updates |
Properties¶
property |
truncated documentation |
---|---|
|
Returns the docname of the document currently being parsed. |
|
contains all existing docnames. |
|
|
|
|
|
|
|
|
|
Get current table. |
|
|
|
Methods¶
method |
truncated documentation |
---|---|
constructor |
|
constructor |
|
constructor |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). … |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). … |
|
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet). … |
|
constructor |
|
Same constructor as Sphinx application. Additional parameters: |
|
Additional initialization steps. |
|
|
|
|
|
|
|
|
|
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
|
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten … |
|
|
Not supported. |
|
Not supported. |
|
Not supported. |
|
Not supported. |
|
Not supported. |
Not supported. |
|
|
Overwrites _write_serial to avoid writing on disk. |
|
Overwrites _write_serial to avoid writing on disk. |
|
Overwrites _write_serial to avoid writing on disk. |
|
Overwrites _write_serial to avoid writing on disk. |
|
Overwrites _write_serial to avoid writing on disk. |
Overwrites _write_serial to avoid writing on disk. |
|
|
Add new options. |
|
Add new options. |
|
Add new options. |
|
Add new options. |
|
Add new options. |
Add new options. |
|
See class Sphinx. |
|
|
Overwrites this method to catch errors due when it is a single document being processed. |
|
Overwrites this method to catch errors due when it is a single document being processed. |
|
Overwrites this method to catch errors due when it is a single document being processed. |
|
Overwrites this method to catch errors due when it is a single document being processed. |
Overwrites this method to catch errors due when it is a single document being processed. |
|
Apply all post-transforms. |
|
|
Overwrites assemble_doctree to control the doctree. |
|
Overwrites assemble_doctree to control the doctree. |
|
Overwrites assemble_doctree to control the doctree. |
|
Overwrites assemble_doctree to control the doctree. |
|
Overwrites assemble_doctree to control the doctree. |
Overwrites assemble_doctree to control the doctree. |
|
|
Adds custom node to the translator. |
|
Adds custom node to the translator. |
|
Adds custom node to the translator. |
|
Adds custom node to the translator. |
|
Adds custom node to the translator. |
Adds custom node to the translator. |
|
Creates a builder, raises an exception if name is None. |
|
|
Returns an instance of translator. This method returns an instance of |
|
Returns an instance of translator. This method returns an instance of |
|
Returns an instance of translator. This method returns an instance of |
|
Returns an instance of translator. This method returns an instance of |
|
Returns an instance of translator. This method returns an instance of |
Returns an instance of translator. This method returns an instance of |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Disables a collector given its class name. |
|
|
|
|
|
|
|
|
|
|
|
Finalizes the documentation after it was parsed. |
|
|
Overwrites fix_refuris to control the reference names. |
|
Overwrites fix_refuris to control the reference names. |
|
Overwrites fix_refuris to control the reference names. |
|
Overwrites fix_refuris to control the reference names. |
|
Overwrites fix_refuris to control the reference names. |
Overwrites fix_refuris to control the reference names. |
|
Read the doctree for a file from the pickle and return it. |
|
|
Overwrites get_target_uri to control file names. |
|
Overwrites get_target_uri to control file names. |
|
Overwrites get_target_uri to control file names. |
|
Overwrites get_target_uri to control file names. |
|
Overwrites get_target_uri to control file names. |
Overwrites get_target_uri to control file names. |
|
|
Overwrites get_target_uri to control the page name. |
|
Overwrites get_target_uri to control the page name. |
|
Overwrites get_target_uri to control the page name. |
|
Overwrites get_target_uri to control the page name. |
|
Overwrites get_target_uri to control the page name. |
Overwrites get_target_uri to control the page name. |
|
Override handle_page to write into stream instead of files. |
|
|
Overrides handle_page to write into stream instead of files. |
|
Overrides handle_page to write into stream instead of files. |
Override handle_page to write into stream instead of files. |
|
Override handle_page to write into stream instead of files. |
|
Overrides handle_page to write into stream instead of files. |
|
|
|
|
Tells if the translator is doctree format. |
|
Tells if the translator is doctree format. |
|
Tells if the translator is doctree format. |
|
Tells if the translator is doctree format. |
Tells if the translator is doctree format. |
|
|
Tells if the translator is html format. |
|
Tells if the translator is html format. |
|
Tells if the translator is html format. |
|
Tells if the translator is html format. |
Tells if the translator is html format. |
|
|
Tells if the translator is latex format. |
|
Tells if the translator is latex format. |
|
Tells if the translator is latex format. |
|
Tells if the translator is latex format. |
Tells if the translator is latex format. |
|
|
Tells if the translator is markdown format. |
|
Tells if the translator is markdown format. |
|
Tells if the translator is markdown format. |
|
Tells if the translator is markdown format. |
Tells if the translator is markdown format. |
|
|
Tells if the translator is rst format. |
|
Tells if the translator is rst format. |
|
Tells if the translator is rst format. |
|
Tells if the translator is rst format. |
Tells if the translator is rst format. |
|
|
Enumerate created pages. |
|
Enumerate created pages. |
|
Enumerate created pages. |
|
Enumerate created pages. |
|
Enumerate created pages. |
Enumerate created pages. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
|
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
|
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
|
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
|
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
Processes a document into its final form. Translates document (a Docutils document tree) into the Writer’s … |
|
|
Documentation¶
Helpers to convert docstring to various format.
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
DocTreeTranslatorWithCustomDirectives
(builder, *args, **kwds)[source]¶ Bases:
pyquickhelper.sphinxext.sphinx_doctree_builder.DocTreeTranslator
See
HTMLWriterWithCustomDirectives
.constructor
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
DocTreeWriterWithCustomDirectives
(builder=None, app=None)[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.
- Parameters
builder – builder
app – Sphinx application
-
translate
()[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]¶ Bases:
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart
,sphinx.writers.html5.HTML5Translator
See
HTMLWriterWithCustomDirectives
.Changed in version 1.7: Does something specific for HTML. only is a node.
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
HTMLWriterWithCustomDirectives
(builder=None, app=None)[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.
- Parameters
builder – builder
app – Sphinx application
-
translate
()[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]¶ Bases:
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart
,pyquickhelper.sphinxext.sphinx_latex_builder.EnhancedLaTeXTranslator
See
LatexWriterWithCustomDirectives
.constructor
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
LatexWriterWithCustomDirectives
(builder=None, app=None)[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.
- Parameters
builder – builder
app – Sphinx application
-
translate
()[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]¶ Bases:
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart
,pyquickhelper.sphinxext.sphinx_md_builder.MdTranslator
See
HTMLWriterWithCustomDirectives
.constructor
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
MDWriterWithCustomDirectives
(builder=None, app=None)[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.
- Parameters
builder – builder
app – Sphinx application
-
translate
()[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]¶ 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.
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
__init__
(app)[source]¶ Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
_writer_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeWriterWithCustomDirectives
-
default_translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeTranslatorWithCustomDirectives
-
handle_page
(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶ Override handle_page to write into stream instead of files.
-
translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeTranslatorWithCustomDirectives
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
MemoryHTMLBuilder
(app)[source]¶ Bases:
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._MemoryBuilder
,pyquickhelper.helpgen._single_file_html_builder.CustomSingleFileHTMLBuilder
Builds HTML output in memory. The API is defined by the page builderapi.
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
__init__
(app)[source]¶ Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
_writer_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLWriterWithCustomDirectives
-
default_translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLTranslatorWithCustomDirectives
-
translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLTranslatorWithCustomDirectives
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
MemoryLatexBuilder
(app)[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.
Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
__init__
(app)[source]¶ Constructs the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
_writer_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexWriterWithCustomDirectives
-
default_translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexTranslatorWithCustomDirectives
-
translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexTranslatorWithCustomDirectives
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
MemoryMDBuilder
(app)[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.
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
__init__
(app)[source]¶ Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
_writer_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDWriterWithCustomDirectives
-
default_translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDTranslatorWithCustomDirectives
-
handle_page
(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶ Override handle_page to write into stream instead of files.
-
translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDTranslatorWithCustomDirectives
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
MemoryRSTBuilder
(app)[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.
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
__init__
(app)[source]¶ Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters
app – Sphinx application
-
_writer_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTWriterWithCustomDirectives
-
default_translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTTranslatorWithCustomDirectives
-
handle_page
(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶ Override handle_page to write into stream instead of files.
-
translator_class
[source]¶ alias of
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTTranslatorWithCustomDirectives
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
RSTTranslatorWithCustomDirectives
(builder, *args, **kwds)[source]¶ Bases:
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper._AdditionalVisitDepart
,pyquickhelper.sphinxext.sphinx_rst_builder.RstTranslator
See
HTMLWriterWithCustomDirectives
.constructor
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
RSTWriterWithCustomDirectives
(builder=None, app=None)[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.
- Parameters
builder – builder
app – Sphinx application
-
translate
()[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]¶ Bases:
object
Additional visitors and departors.
Changed in version 1.7: Update for Sphinx 1.7.
New in version 1.7.
-
add_secnumber
(node)[source]¶ Overwrites this method to catch errors due when it is a single document being processed.
-
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
_CustomBuildEnvironment
(app)[source]¶ Bases:
sphinx.environment.BuildEnvironment
Overrides some functionalities of BuildEnvironment.
-
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]¶ Bases:
sphinx.application.Sphinx
Custom Sphinx application to avoid using disk.
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')}
-
__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]¶ 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')}
-
add_builder
(builder, override=False)[source]¶ 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_=())[source]¶ Register a configuration value.
This is necessary for Sphinx to recognize new values and set default values accordingly.
- Parameters
name – The name of 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, **kwargs)[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 in order of priority (ascending). The filename must be relative to the HTML static path, or a full URI with scheme. If the priority of CSS file is the same as others, the CSS files will be included in order of the registration. 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" />
priority range for CSS files¶ Priority
Main purpose in Sphinx
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 on extension calls this method on :event:`html-page-context` event.
New in version 1.0.
Changed in version 1.6: Optional
alternate
and/ortitle
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.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)[source]¶ Register a Docutils directive.
- Parameters
name – The 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
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): 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)[source]¶ 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)[source]¶ 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)[source]¶ See class Sphinx.
-
add_event
(name)[source]¶ 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)[source]¶ 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, **kwargs)[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 in order of priority (ascending). The filename must be relative to the HTML static path , or a full URI with scheme. If the priority of JavaScript file is the same as others, the JavaScript files will be included in order of the registration. If the keyword argument
body
is given, its value will be added between the<script>
tags. Extra keyword arguments are included as attributes of the<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> 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 on 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.
-
add_latex_package
(packagename, options=None, after_hyperref=False)[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. 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)[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.
- 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 beNone
if thevisit
function raisesdocutils.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]¶ 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 aredocutils.nodes.emphasis
ordocutils.nodes.strong
– you can also usedocutils.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, usesphinx.addnodes.literal_emphasis
orsphinx.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)[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.- Parameters
transform – A transform class
-
add_role
(name, role, override=True)[source]¶ 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)[source]¶ 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 target domain
name – A 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
New in version 1.0.
Changed in version 1.8: Add override keyword.
-
add_transform
(transform)[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.- 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.
-
disconnect_env_collector
(clname, exc=True)[source]¶ Disables a collector given its class name.
- Parameters
cl – name
exc – raises an exception if not found
- Returns
found collector
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
_MemoryBuilder
[source]¶ Bases:
object
Builds HTML output in memory. The API is defined by the page builderapi.
-
_init
(base_class, app)[source]¶ 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
-
create_translator
(*args)[source]¶ Returns an instance of translator. This method returns an instance of
default_translator_class
by default. Users can replace the translator class withapp.set_translator()
API.
-
handle_page
(pagename, addctx, templatename='page.html', outfilename=None, event_arg=None)[source]¶ Overrides handle_page to write into stream instead of files.
-
-
class
pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.
_WriterWithCustomDirectives
[source]¶ Bases:
object
Common class to
HTMLWriterWithCustomDirectives
andRSTWriterWithCustomDirectives
.-
_init
(base_class, translator_class, app=None)[source]¶ - Parameters
base_class – base class
app – Sphinx application
-
add_configuration_options
(new_options)[source]¶ Add new options.
- Parameters
new_options – new options
-
connect_directive_node
(name, f_visit, f_depart)[source]¶ Adds custom node to the translator.
- Parameters
name – name of the directive
f_visit – visit function
f_depart – depart function
-