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, itstitle
. 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 optiontitle
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:- If parent is
_default_
, the parent is the last observed section (as per sphinx-dictated order oftraverse
) whose depth is one less than this section. - If parent is the title of another section, that section will be forced to be the parent of this section.
- 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
()¶
- If parent is
-
sphinxcontrib.wiki.
doctree_read
(app, doctree)¶ Handler for sphinx’s
doctree-read
event. This is where we remove allwikisection
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 allwikipage
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:
- The configuration parameter
wiki_enabled
, defaulting toFalse
which turns our behavior on and off. - Two node types:
wikisection
, andwikipage
. - Two directives:
wikisection
, andwikipage
with handlersWikiSection
andWikiPage
. - Four hooks, two of which –
doctree_read()
anddoctree_resolved()
– are involved in moving sections from their original place to where the corresponding page is included. The other two –env_purge_doc()
andenv_merge_info()
– are implemented to make our usage of the build environment parallel-friendly.
- The configuration parameter
-
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 thewikisection
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
- env – The build environment (i.e an instance of
-
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: 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
- app – The “application”, instance of