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

_modify_postcontents

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

Properties

property

truncated documentation

document

Return the document root node of the tree containing this Node.

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]

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.

source on GitHub

has_content = True[source]

May the directive have content?

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

source on GitHub

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

does nothing

source on GitHub

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

Bases: paragraph

defines postcontents node

source on GitHub

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.

source on GitHub

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

setup for postcontents (sphinx)

source on GitHub

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 function nested_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).

source on GitHub

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

does nothing

source on GitHub