module sphinxext.sphinx_postcontents_extension
¶
Short summary¶
module pyquickhelper.sphinxext.sphinx_postcontents_extension
Defines a sphinx extension which proposes a new version of .. contents::
which takes into account titles dynamically added.
Classes¶
class |
truncated documentation |
---|---|
defines |
|
Defines a sphinx extension which proposes a new version of `` |
Functions¶
function |
truncated documentation |
---|---|
does nothing |
|
Collect all postcontents in the environment. Look for the section or document which contain them. Put them into … |
|
setup for |
|
The function is called by event |
|
does nothing |
Properties¶
property |
truncated documentation |
---|---|
|
Return the document root node of the tree containing this Node. |
Methods¶
method |
truncated documentation |
---|---|
Just add a |
Documentation¶
Defines a sphinx extension which proposes a new version of .. contents::
which takes into account titles dynamically added.
- class pyquickhelper.sphinxext.sphinx_postcontents_extension.PostContentsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]¶
Bases:
Directive
Defines a sphinx extension which proposes a new version of
.. contents::
which takes into account titles dynamically added.Example:
.. postcontents:: title 1 ======= .. runpython:: :rst: print("title 2") print("=======")
Which renders as:
Directive
.. contents::
only considers titles defined by the user, not titles dynamically created by another directives.Warning
It is not recommended to dynamically insert such a directive. It is not recursive.
- node_class[source]¶
alias of
postcontents_node
- option_spec = {'depth': <function unchanged>, 'local': <function unchanged>}[source]¶
Mapping of option names to validator functions.
- run()[source]¶
Just add a
postcontents_node
.- Returns:
list of nodes or list of nodes, container
- pyquickhelper.sphinxext.sphinx_postcontents_extension.depart_postcontents_node(self, node)[source]¶
does nothing
- class pyquickhelper.sphinxext.sphinx_postcontents_extension.postcontents_node(rawsource='', text='', *children, **attributes)[source]¶
Bases:
paragraph
defines
postcontents
node
- pyquickhelper.sphinxext.sphinx_postcontents_extension.process_postcontents(app, doctree)[source]¶
Collect all postcontents in the environment. Look for the section or document which contain them. Put them into the variable postcontents_all_postcontents in the config.
- pyquickhelper.sphinxext.sphinx_postcontents_extension.setup(app)[source]¶
setup for
postcontents
(sphinx)
- pyquickhelper.sphinxext.sphinx_postcontents_extension.transform_postcontents(app, doctree, fromdocname)[source]¶
The function is called by event
'doctree_resolved'
. It looks for every section in page stored in postcontents_all_postcontents in the configuration and builds a short table of contents. The instruction.. contents::
is resolved before every directive in the page is executed, the instruction.. postcontents::
is resolved after.- Parameters:
app – Sphinx application
doctree – doctree
fromdocname – docname
Thiis directive should be used if you need to capture a section which was dynamically added by another one. For example
RunPythonDirective
calls functionnested_parse_with_titles
... postcontents::
will capture the new section this function might eventually add to the page. For some reason, this function does not seem to be able to change the doctree (any creation of nodes is not taken into account).