Wiki

Introduction

Basic usage

sphinxcontrib-wiki is a Sphinx extension which allows wiki pages to be automatically generated from docstrings. Here is an example:

.. wikisection:: example
    :title: Example wiki section title

    Wiki sections must have a body or they are ignored.

Wiki pages are generated like this:

.. wikipage:: example
    :title: Example wiki section

    Body of a wiki page appears above all its sections.

_{[source: sphinxcontrib.wiki]}

Section Hierarchy

By default, the structure of the wikisection tree within a wikipage is determined by module hierarchy, namely:

• Sections within a module are treated as siblings in the order they appear regardless of the depth of the class or function they belong to.
• Sections within sibling modules are treated as siblings in _alphabetic_ order (and not as they are processed as per autodoc_member_order).
• Sections within a package are treated as the parent of those in modules immediately within it.

Alternatively, a section can force its parent to a be specific other section, for instance:

.. wikisection:: example
    :title: A section with forced parent
    :parent: Example wiki section title

    Mandatory section body.

_{[source: sphinxcontrib.wiki]}

Potentially Asked Questions

Section Reuse

It may be desirable to reuse the same section in different wiki pages. This is currently not possible as it requires rethinking the parent option. One possibility is to extend the syntax as follows:

.. wikisection:: first, second
    :title: Section belonging to many pages
    :parents: first[Parent in first page], second[_default_]

Another possibility is to invert the control and let pages decide their hierarchy, requiring some preprocessing on raw sources:

.. wikipage:: example
    :tree:
        section1
            section1.1
            section1.2
        section2

_{[source: sphinxcontrib.wiki]}

Section within Sections

Title elements are not allowed in docstring by docutils or sphinx. Other extensions that require this functionality, e.g. numpy, implement their own preprocessing methods (cf. source-read event by sphinx). The possible ways nested sections can be achieved by sphinxcontrib-wiki are:

• Separate out the subsection into a wikisection of its own and assign its parent to the parent wikisection, for instance:

  .. wikisection:: example
      :title: Parent Section
  
      Body of parent.
  
  .. wikisection:: example
      :title: Child Section
      :parent: Parent Section
  
      Body of child.
  

• Use the rubric directive which allows adding a title within a directive body but whose information is lost to the table of contents.

_{[source: sphinxcontrib.wiki]}

Arbitrary Order of Processing

As long as the order in which sections are encountered is consistent with a DFS of the module hierarchy, i.e up to reorderings of siblings but not violating depth order, there are no problems. The DFS order is what sphinx follows and the only possible chance of variation is in sibling order caused by autodoc_member_order (and our output respects this sibling order by default). But if for some reason, this assumption is violated, i.e a section appearing deeper in the module hierarchy is encountered before another section appearing shallower in the module hierarchy, our logic for placing sections in the right place breaks.

_{[source: sphinxcontrib.wiki]}

Cycles in parent relationships

If there are any cycles in the parent relationships the entire set of sections within that cycle are swallowed by docutils. Since there is no error raised or warning issued, this extension cannot inform the user either. Checking for cycles requires a quadratic effort to scan the entire parent-child graph which currently seems unnecessary.

_{[source: sphinxcontrib.wiki]}

Resolving References

The current implementation stores all sections in the build environment after doctree-read and uses them to populate all pages upon doctree-resolved. This is needed to allow all sections to be collected before any page is assembled.

_{[source: sphinxcontrib.wiki]}

To Do List

Report

Sphinx API documentation for developing extensions is not friendly to newcomers. Document the available sources (docutils, sphinx, and extensions in sphinxcontrib) and the basics of creating an extension.

_{[source: sphinxcontrib.wiki]}

Tree documentation

Document more clearly how the wiki page tree structure is determined by default: it’s all in the dots in rst document name, i.e ideally for python packages and potentially confusing otherwise.

_{[source: sphinxcontrib.wiki]}