Competing Solutions

The roles and each directive have competitors solving a part of their task; none of them is one extension covering all of them.

Outside Python, XML editors generate the documentation of an XML schema - e.g. Oxygen XML Editor writes HTML or PDF pages listing every component, with diagrams - but outside the Sphinx build.

docutils Roles

Source: the role and raw directives of docutils, compared to the roles.

Disadvantages

  • A role created by .. role:: only sets a CSS class, so every project writes the stylesheet itself, and declares the role in every document or in rst_prolog.

  • A line break written with raw is written once per output format - html and latex.

Advantages

  • No extension is needed.

autodoc and AutoAPI

Source: sphinx.ext.autodoc and sphinx.ext.autosummary of Sphinx, and Sphinx AutoAPI, on PyPI as sphinx-autoapi, compared to condensed-class.

Disadvantages

  • They document every member with its doc-string, or list members in a table, rather than showing a class’ interface as one code block.

  • autodoc imports the module, so an annotation is rendered as it resolves, not as it is written.

Standoff

  • AutoAPI parses the source instead of importing it, as condensed-class does.

Advantages

  • Complete API documentation of modules, classes and functions, cross-referenced, not just one class’ interface.

Dependency Lists

Source: sphinxcontrib-requirements-txt, on PyPI as sphinxcontrib-requirements-txt (last release 2023), and pip-licenses, compared to dependency-table.

Disadvantages

  • sphinxcontrib-requirements-txt renders the lines of requirements files through a Jinja2 template. It asks no package index, so it shows neither licenses nor the dependencies of a dependency.

  • pip-licenses is a command line tool, not a directive. It reports the packages installed in the environment it runs in, as a flat list, so its table is generated and committed, or included by another extension.

Advantages

  • pip-licenses writes many formats - among them a reST grid table - and can fail on licenses that aren’t allowed.

Schema Documentation

Source: sphinx-jsonschema, on PyPI as sphinx-jsonschema, compared to xmlschema-graph.

Disadvantages

  • sphinx-jsonschema renders a JSON schema, not an XML schema, and as tables rather than as a graph.

Advantages

  • sphinx-jsonschema shows every property with its description.

sphinx-toolbox Shields

Source: sphinx-toolbox, on PyPI as sphinx-toolbox, its extension sphinx_toolbox.shields, compared to shields.

Disadvantages

  • Every badge is a directive of its own - pypi-shield, github-shield, actions-shield and others - so the project’s coordinates are repeated per badge, and the rows are laid out by hand.

Advantages

  • Badges of services shields doesn’t know, e.g. Read the Docs, Coveralls, CodeFactor and pre-commit.

  • It is one extension of a larger collection.