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(document, builder, *args, **kwds)[source]¶
Bases:
DocTreeTranslator
See
HTMLWriterWithCustomDirectives
.constructor
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.DocTreeWriterWithCustomDirectives(builder=None, app=None)[source]¶
Bases:
_WriterWithCustomDirectives
,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(document, builder, *args, **kwds)[source]¶
Bases:
_AdditionalVisitDepart
,HTML5Translator
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.HTMLWriterWithCustomDirectives(builder=None, app=None)[source]¶
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.
- 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(document, builder, *args, **kwds)[source]¶
Bases:
_AdditionalVisitDepart
,EnhancedLaTeXTranslator
See
LatexWriterWithCustomDirectives
.constructor
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.LatexWriterWithCustomDirectives(builder=None, app=None)[source]¶
Bases:
_WriterWithCustomDirectives
,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(document, builder, *args, **kwds)[source]¶
Bases:
_AdditionalVisitDepart
,MdTranslator
See
HTMLWriterWithCustomDirectives
.constructor
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MDWriterWithCustomDirectives(builder=None, app=None)[source]¶
Bases:
_WriterWithCustomDirectives
,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, env=None)[source]¶
Bases:
_MemoryBuilder
,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, env=None)[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
DocTreeWriterWithCustomDirectives
- handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶
Override handle_page to write into stream instead of files.
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryHTMLBuilder(app, env=None)[source]¶
Bases:
_MemoryBuilder
,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, env=None)[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
HTMLWriterWithCustomDirectives
- default_translator_class[source]¶
alias of
HTMLTranslatorWithCustomDirectives
- supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg'][source]¶
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
- translator_class[source]¶
alias of
HTMLTranslatorWithCustomDirectives
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryLatexBuilder(app, env=None)[source]¶
Bases:
_MemoryBuilder
,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, env=None)[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
LatexWriterWithCustomDirectives
- default_translator_class[source]¶
alias of
LatexTranslatorWithCustomDirectives
- supported_image_types: list[str] = ['image/png', 'image/jpeg', 'image/gif'][source]¶
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
- translator_class[source]¶
alias of
LatexTranslatorWithCustomDirectives
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryMDBuilder(app, env=None)[source]¶
Bases:
_MemoryBuilder
,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, env=None)[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
MDWriterWithCustomDirectives
- default_translator_class[source]¶
alias of
MDTranslatorWithCustomDirectives
- handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶
Override handle_page to write into stream instead of files.
- supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg'][source]¶
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
- translator_class[source]¶
alias of
MDTranslatorWithCustomDirectives
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.MemoryRSTBuilder(app, env=None)[source]¶
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.
Construct the builder. Most of the parameter are static members of the class and cannot be overwritten (yet).
- Parameters:
app – Sphinx application
- __init__(app, env=None)[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
RSTWriterWithCustomDirectives
- default_translator_class[source]¶
alias of
RSTTranslatorWithCustomDirectives
- handle_page(pagename, addctx, templatename=None, outfilename=None, event_arg=None)[source]¶
Override handle_page to write into stream instead of files.
- supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg'][source]¶
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
- translator_class[source]¶
alias of
RSTTranslatorWithCustomDirectives
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTTranslatorWithCustomDirectives(document, builder, *args, **kwds)[source]¶
Bases:
_AdditionalVisitDepart
,RstTranslator
See
HTMLWriterWithCustomDirectives
.constructor
- class pyquickhelper.helpgen.sphinxm_convert_doc_sphinx_helper.RSTWriterWithCustomDirectives(builder=None, app=None)[source]¶
Bases:
_WriterWithCustomDirectives
,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.
- 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:
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
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, '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')}
- __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, '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')}
- 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_=(), 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 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)[source]¶
Register a stylesheet to include in the HTML output.
- Parameters:
filename – The name of a CSS file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme.
priority – Files are included in ascending order of priority. If multiple CSS files have the same priority, those files will be included in order of registration. See list of “priority range for CSS files” below.
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
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/ortitle
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)[source]¶
Register a Docutils directive.
- Parameters:
name – The name of the directive
cls – A directive class
override – If false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive.
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)[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 false, do not install it if another directive is already installed as the same name If true, unconditionally install the directive.
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 false, do not install it if another domain is already installed as the same name If true, unconditionally install the domain.
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.
- Parameters:
override – If false, do not install it if another role is already installed as the same name If true, unconditionally install the role.
New in version 0.6.
Changed in version 1.8: Add override keyword.
- add_js_file(filename, priority=500, **kwargs)[source]¶
Register a JavaScript file to include in the HTML output.
- Parameters:
filename – The name of a JavaScript file that the default HTML template will include. It must be relative to the HTML static path, or a full URI with scheme, or
None
. TheNone
value is used to create an inline<script>
tag. See the description of kwargs below.priority – Files are included in ascending order of priority. If multiple JavaScript files have the same priority, those files will be included in order of registration. See list of “priority range for JavaScript files” below.
loading_method – The loading method for the JavaScript file. Either
'async'
or'defer'
are allowed.kwargs – Extra keyword arguments are included as attributes of the
<script>
tag. If the special keyword argumentbody
is given, its value will be added as the content of 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
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)[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 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)[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 false, do not install it if another role is already installed as the same name If true, unconditionally install the role.
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 the target domain
name – The name of the role
role – The role function
override – If false, do not install it if another role is already installed as the same name If true, unconditionally install the role.
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
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, env=None)[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
env – Environment
- 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