pestifer.sphinxext.sphinx_examplemanager module

This module provides the SphinxExampleManager class, which allows for the management of examples in the documentation. It includes methods to add, update, and delete examples. It also provides functionality to modify the TOC tree for the main examples RST file. This is typically the file docs/source/examples.rst in the package.

Files pertaining to documentation of specific examples are stored in docs/source/examples/ex##/ where ## is the two-digit unique ID for the example. The RST file in each folder should have the name <shortname>.rst, where <shortname> is the name of the example (the ‘shortname’ attribute of the associated :class:~pestifer.core.example.Example instance).

class pestifer.sphinxext.sphinx_examplemanager.SphinxExampleManager(docs_source_path=None, examples_folder_name='examples', examples_rst_name='examples.rst')

Bases: object

Sphinx extension to manage examples in the documentation.

This extension allows for the inclusion of example input files in the documentation. It provides a way to link examples to their documentation and manage example files.

docs_source_path

The path to the source directory (typically PACKAGE/docs/source) containing documentation files parseable by Sphinx.

Type:

str

append_example(example: Example)

Add an example to the documentation

Parameters:

example (Example) – The example to add.

delete_example(example: Example)

Delete an example from the examples RST file. This method first searches the TOC tree for the example’s name, then deletes the corresponding file in the examples source path (typically docs/source/examples/name.rst). Since the examples are ordered by their position in the TOC tree, this method will also shift the indices of subsequent examples down by one, by editing the titles of their respective RST files.

Parameters:

example (Example) – The example to delete.

new_rst(example: Example)

Create a new RST file for the example.

Parameters:

example (Example) – The example to create an RST file for.

Returns:

The contents of then new RST file

Return type:

str

structure_url(example: Example) → str

update_example(example_id: int, example: Example)

Update an existing example’s documentation with content in example

Parameters:

• example_id (int) – The unique ID of the example to update.

• example (Example) – The example whose content will be used to update the existing example