module sphinxext.sphinx_tocdelay_extension

Short summary

module pyquickhelper.sphinxext.sphinx_tocdelay_extension

Defines a sphinx extension which proposes a new version of .. toctree:: which takes into account titles dynamically added.

source on GitHub

Classes

class	truncated documentation
tocdelay_node	defines tocdelay node
TocDelayDirective	Defines a sphinx extension which proposes a new version of ``

Functions

function	truncated documentation
_print_loop_on_children
depart_tocdelay_node	does nothing
process_tocdelay	Collect all tocdelay in the environment. Look for the section or document which contain them. Put them into the …
setup	setup for tocdelay (sphinx)
transform_tocdelay	The function is called by event 'doctree_resolved'. It looks for every section in page stored in tocdelay_all_tocdelay …
visit_tocdelay_node	does nothing

Properties

property	truncated documentation
document	Return the document root node of the tree containing this Node.

Methods

method	truncated documentation
run	Just add a tocdelay_node and list the documents to add.

Documentation

Defines a sphinx extension which proposes a new version of .. toctree:: which takes into account titles dynamically added.

source on GitHub

class pyquickhelper.sphinxext.sphinx_tocdelay_extension.TocDelayDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: Directive

Defines a sphinx extension which proposes a new version of .. toctree:: which takes into account titles dynamically added. It only considers one level.

Example:

.. tocdelay::

    document

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

Parameter rule implements specific behaviors. It contains the name of the node which holds the document name, the title, the id. In case of the blog, the rule is: blogpost_node,toctitle,tocid,tocdoc. That means the TocDelayDirective will look for nodes blogpost_node and fetch attributes toctitle, tocid, tocdoc to fill the toc contents. No depth is allowed at this point. The previous value is the default value. Option path is mostly used to test the directive.

source on GitHub

has_content = True

May the directive have content?

node_class

alias of tocdelay_node

option_spec = {'path': <function unchanged>, 'rule': <function unchanged>}

Mapping of option names to validator functions.

run()

Just add a tocdelay_node and list the documents to add.

Returns:

of nodes or list of nodes, container

source on GitHub

pyquickhelper.sphinxext.sphinx_tocdelay_extension._print_loop_on_children(node, indent='', msg='-')

pyquickhelper.sphinxext.sphinx_tocdelay_extension.depart_tocdelay_node(self, node)

does nothing

source on GitHub

pyquickhelper.sphinxext.sphinx_tocdelay_extension.process_tocdelay(app, doctree)

Collect all tocdelay in the environment. Look for the section or document which contain them. Put them into the variable tocdelay_all_tocdelay in the config.

source on GitHub

pyquickhelper.sphinxext.sphinx_tocdelay_extension.setup(app)

setup for tocdelay (sphinx)

source on GitHub

class pyquickhelper.sphinxext.sphinx_tocdelay_extension.tocdelay_node(rawsource='', text='', *children, **attributes)

Bases: paragraph

defines tocdelay node

source on GitHub

__slotnames__ = []

pyquickhelper.sphinxext.sphinx_tocdelay_extension.transform_tocdelay(app, doctree, fromdocname)

The function is called by event 'doctree_resolved'. It looks for every section in page stored in tocdelay_all_tocdelay in the configuration and builds a short table of contents. The instruction .. toctree:: is resolved before every directive in the page is executed, the instruction .. tocdelay:: 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 function nested_parse_with_titles. .. tocdelay:: will capture the new section this function might eventually add to the page.

source on GitHub

pyquickhelper.sphinxext.sphinx_tocdelay_extension.visit_tocdelay_node(self, node)

does nothing

source on GitHub