Sphinx

https://www.sphinx-doc.org/en/master/

How to ad-hoc silence unreferenced footnote warnings

E.g.: WARNING: Footnote %s is not referenced.

Self reference it 5head:

.. [1] Foo [1]_

Multiple top-level headlines in a document

It is possible to have multiple headlines at the top level in a single document. These top level headlines will be rendered in the “above” toctrees in order.

Logical, but maybe non-obvious.

Extensions

  • Sphinx Design - https://sphinx-design.readthedocs.io/

    • lots of modern html elements

    • widely compatible

    • this looks great

  • Immaterial https://jbms.github.io/sphinx-immaterial/admonitions.html

    • Admonitions look nice

    • Makes admonition content into collapsible dropdown

  • Furo https://pradyunsg.me/furo/

    • Admonitions look nice

  • Sphinx toolbox https://sphinx-toolbox.readthedocs.io/en/stable/extensions/github.html

    Collections of various more or less useful extensions, notably:

    • sidebar_links - add additional sections to the main sidebar

    • confval - for documenting config values

    • assets - not sure how is this better than using the static dir or similar

    • changeset - directives for “New in version …”, etc. Is python.org using this?

    • collapse - adds collapsible paragraphs

    • installation - directive for installation instructions. This is interesting because it displays them horinzontally tabbed.

    • latex - correctly handles symbol footnotes

    • rest_example - for documenting rest usage

    • shields - shields/badges directives. Useful only as a reference as to types of badges.

    • autodoc - more autodoc features, might be something useful

    • tweaks - tweaks.param_dash lmao. Why isnt this upstream?

    • the rest is mostly useless for html