module sphinxext.sphinx_postcontents_extension

Inheritance diagram of pyquickhelper.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.

source on GitHub

Classes

class

truncated documentation

postcontents_node

defines postcontents node

PostContentsDirective

Defines a sphinx extension which proposes a new version of ``

Functions

function

truncated documentation

depart_postcontents_node

does nothing

process_postcontents

Collect all postcontents in the environment. Look for the section or document which contain them. Put them into …

setup

setup for postcontents (sphinx)

transform_postcontents

The function is called by event 'doctree_resolved'. It looks for every section in page stored in postcontents_all_postcontents

visit_postcontents_node

does nothing

Methods

method

truncated documentation

run

Just add a postcontents_node.

Documentation

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

source on GitHub

class pyquickhelper.sphinxext.sphinx_postcontents_extension.PostContentsDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source][source]

Bases: docutils.parsers.rst.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.

source on GitHub

node_class[source]

alias of postcontents_node

run()[source][source]

Just add a postcontents_node.

Returns

list of nodes or list of nodes, container

source on GitHub

pyquickhelper.sphinxext.sphinx_postcontents_extension.depart_postcontents_node(self, node)[source][source]

does nothing

source on GitHub

class pyquickhelper.sphinxext.sphinx_postcontents_extension.postcontents_node(rawsource='', text='', *children, **attributes)[source][source]

Bases: docutils.nodes.paragraph

defines postcontents node

source on GitHub

pyquickhelper.sphinxext.sphinx_postcontents_extension.process_postcontents(app, doctree)[source][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.

source on GitHub

pyquickhelper.sphinxext.sphinx_postcontents_extension.setup(app)[source][source]

setup for postcontents (sphinx)

source on GitHub

pyquickhelper.sphinxext.sphinx_postcontents_extension.transform_postcontents(app, doctree, fromdocname)[source][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 function nested_parse_with_titles. .. postcontents:: will capture the new section this function might eventually add to the page.

source on GitHub

pyquickhelper.sphinxext.sphinx_postcontents_extension.visit_postcontents_node(self, node)[source][source]

does nothing

source on GitHub