Skip to main content

Sphinx DocumentedList extension

Project description

This file provides a Sphinx extension to convert a Python list into a table in the generated documentation. The intended application of this extension is to document the items of essentially list-like objects of immutable data (possibly enums, though python 3.4 enums are not supported yet).

In the source code, each list item, instead of being just it’s native data type, should be replaced by a tuple of two elements. In the simpest application, the second element of the tuple should be a string which provides a description for the item.

The following options are also included to enable slightly more complex use cases :

header:

The number of columns displayed is 2 by default, with titles “Item” and “Description”. This option allows you to add a custom header and change the number of columns in the table:

.. documentedlist::
    :listobject: some.list.object
    :header: "First Name" "Last Name" Email
spantolast:

If this flag is present, the last column of any row with an insufficient number of columns will spread to span all remaining columns. This would typically be used to insert headings within the table:

.. documentedlist::
    :listobject: some.list.object
    :spantolast:
descend:

This flag allows you to construct a relatively complex table. with subsections. Any row containing a list as one of it’s cells is expanded into a sub-table (specifically, a docutils tgroup). The list is popped from the original row, and each element of the list is turned into a row:

.. documentedlist::
    :listobject: some.list.object
    :descend:

In the first use of this extension, the aim was to document a list of supported device classes (each of which is a string). This was originally specified in the python code as a list, and the same list with descriptions was manually maintained (or, in reality, left unmaintained) in the corresponding documentation. The list is now replaced with a tuple containing both the recognized strings and the description for each, and Sphinx is able to use this extension to ‘autogenerate’ the table in the documentation.

Based heavily on slides from Doug Hellman’s PyCon talk, http://www.slideshare.net/doughellmann/better-documentation-through-automation-creating-docutils-sphinx-extensions

Installation & Usage

This extension is part of the sphinxcontrib namespace and can be installed from pypi :

pip install sphinxcontrib-documentedlist

In the .rst file where the table should appear, insert the Sphinx directive provided by this module :

.. documentedlist::
    :listobject: full.importable.path.of.thelist

This extension will import the list as :

from full.importable.path.of import thelist

For a basic usage example, see:

Python:

https://github.com/chintal/tendril/blob/master/tendril/conventions/electronics.py#L28

ReST:

https://raw.githubusercontent.com/chintal/tendril/master/doc/userdoc/conventions/gedasymbols.rst (Device Classes)

Generated:

http://tendril.chintal.in/doc/userdoc/conventions/gedasymbols/#device-classes

For a more complex example of the extension’s usage, including the :header:, :spantolast:, and :descend: options, see:

Python:

https://github.com/chintal/tendril/blob/master/tendril/utils/config.py#L791

ReST:

https://github.com/chintal/tendril/blob/master/tendril/utils/config.py#L67

Generated:

http://tendril.chintal.in/doc/apidoc/tendril.utils.config/#configuration-options

License

This Sphinx Extension is made available under the BSD 2-clause License. See sphinxcontrib’s LICENSE file for the full text.

Thanks

  • Maximilian Hils (github @mhils)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinxcontrib-documentedlist-0.6.tar.gz (5.0 kB view details)

Uploaded Source

Built Distributions

File details

Details for the file sphinxcontrib-documentedlist-0.6.tar.gz.

File metadata

File hashes

Hashes for sphinxcontrib-documentedlist-0.6.tar.gz
Algorithm Hash digest
SHA256 0ca2009a577b3e3b2a5dabef8c0e2d5067be8ffda84f893ca356a8a9784fc21a
MD5 1264cfb59fe7e25d6a47ab0fd25f81f3
BLAKE2b-256 545b7ad0611265968605e2d188376b2ee729716d781d5e9b184bb559180b29b2

See more details on using hashes here.

File details

Details for the file sphinxcontrib_documentedlist-0.6-py3-none-any.whl.

File metadata

  • Download URL: sphinxcontrib_documentedlist-0.6-py3-none-any.whl
  • Upload date:
  • Size: 6.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.30.0 CPython/3.7.2

File hashes

Hashes for sphinxcontrib_documentedlist-0.6-py3-none-any.whl
Algorithm Hash digest
SHA256 d0150b6118e156cc94569ca4b9a445ef18749ba26088c1a0470bdbcdc89fa526
MD5 3cb0195672c0b61a7bcc1c4c55f57532
BLAKE2b-256 26fc6629fac55f24a9497c41f91f533f021ee5e6161f6d6f3a1b79bd3e03f065

See more details on using hashes here.

File details

Details for the file sphinxcontrib_documentedlist-0.6-py2-none-any.whl.

File metadata

File hashes

Hashes for sphinxcontrib_documentedlist-0.6-py2-none-any.whl
Algorithm Hash digest
SHA256 ea545729c8b22d32027e6b7632bd71e662c5042e03cf7afd6891b92ae127b18d
MD5 2bbe95d735566a1f3f16e58d59c562e3
BLAKE2b-256 591c79f6a364b4e31a030e63b2997aa75625e6d7a451c4612992f421dbcceb70

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page