sphinxcontrib.wiki module

Allow wiki pages to be automatically generated from docstrings.

class sphinxcontrib.wiki.WikiPage(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Handler for the wikipage directive. Each page has one required argument, its identifier and a required option, its title. Optionally, a page can have a body which will be rendered above all its child sections.

has_content = True
option_spec = {'title': <function unchanged>}
optional_arguments = 0
required_arguments = 1
run()
class sphinxcontrib.wiki.WikiSection(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Handler for the wikisection directive. Each section has one reqiured argument, the identifier of the wikipage to which it belongs, and one required option title which is used by other sections to reference it. Furthermore, each section must have a non-empty body.

By default, the placement of each section, and thus the depth of its title heading, is automatically calculated based on the package hirerarchy. Optionally, the parent of the section in the page tree, which is another section, can be specified as an option, default is _default_. Parent resolution is performed as follows:

  1. If parent is _default_, the parent is the last observed section (as per sphinx-dictated order of traverse) whose depth is one less than this section.
  2. If parent is the title of another section, that section will be forced to be the parent of this section.
  3. If parent is _none_, this section is placed in the top level of the corresponding wiki page.
has_content = True
node_class

alias of wikisection

option_spec = {'parent': <function unchanged>, 'title': <function unchanged>}
optional_arguments = 0
required_arguments = 1
run()
sphinxcontrib.wiki.doctree_read(app, doctree)

Handler for sphinx’s doctree-read event. This is where we remove all wikisection nodes from the doctree and store them in the build environment.

sphinxcontrib.wiki.doctree_resolved(app, doctree, docname)

Handler for sphinx’s doctree-resolved event. This is where we replace all wikipage nodes based on the stored sections from the build environment and resolve all references.

sphinxcontrib.wiki.env_merge_info(app, env, docnames, other)

Standard handler for sphinx’s env-murge-info event. We need to implement this because we store data in the build environment, cf. sphinx.ext.todo.

sphinxcontrib.wiki.env_purge_doc(app, env, docname)

Standard handler for sphinx’s env-purge-doc event. We need to implement this because we store data in the build environment, cf. sphinx.ext.todo.

sphinxcontrib.wiki.setup(app)

Entry point to sphinx. We define:

  1. The configuration parameter wiki_enabled, defaulting to False which turns our behavior on and off.
  2. Two node types: wikisection, and wikipage.
  3. Two directives: wikisection, and wikipage with handlers WikiSection and WikiPage.
  4. Four hooks, two of which – doctree_read() and doctree_resolved() – are involved in moving sections from their original place to where the corresponding page is included. The other two – env_purge_doc() and env_merge_info() – are implemented to make our usage of the build environment parallel-friendly.
class sphinxcontrib.wiki.wikipage(rawsource='', *children, **attributes)

Bases: docutils.nodes.General, docutils.nodes.Element

sphinxcontrib.wiki.wikipage_container(env, sec_tree, page_node)

Builds a sphinx section corresponding to a wikipage provided the wikisection tree for it is given.

Parameters:
  • env – The build environment (i.e an instance of sphinx.environment.BuildEnvironment).
  • sec_tree – A list of sphinx sections at the top level of the tree.
  • page_node – The wikipage node as observed in some document.
Returns:

A sphinx section containing the wiki page.
Return type:

sphinx.util.compat.nodes.section
sphinxcontrib.wiki.wikipage_tree(app, env, docname, page_node=None)

Builds a section tree for a given wikipage node by collecting all wikisections from the environment and placing them in the right place.

Parameters:
  • app – The “application”, instance of sphinx.application.Sphinx.
  • env – The build environment (i.e an instance of sphinx.environment.BuildEnvironment).
  • docname – The document name where this wikipage was found.
  • page_node – The wikipage node as observed in some document.
Returns:

A list of top level sections.
Return type:

list[sphinx.util.compat.nodes.section]
class sphinxcontrib.wiki.wikisection(rawsource='', *children, **attributes)

Bases: docutils.nodes.section

sphinxcontrib.wiki.wikisection_container(app, env, sec_info)

Builds a sphinx section corresponding to a given wikisection.

Parameters:
  • app – The “application”, instance of sphinx.application.Sphinx.
  • env – The build environment (i.e an instance of sphinx.environment.BuildEnvironment).
  • sec_info – A dictionary containing stored info about one section, cf. doctree_read().
Returns:

The sphinx section containing the given wiki section.
Return type:

sphinx.util.compat.nodes.section