Awesome Sphinx (Python Documentation Generator)

A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Generator). Inspired by awesome-sqlalchemy. (See also other awesome lists!)

Licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.

Your contributions are welcome.

Table of Contents

Sphinx
Articles & Presentations
Extensions
Internationalizations
Miscellaneous
Themes
Publication

Sphinx

Wikipedia: https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)

Homepage: https://www.sphinx-doc.org/

Source: git https://github.com/sphinx-doc/sphinx

Docs: https://www.sphinx-doc.org/en/master/contents.html

Docs: https://www.sphinx-doc.org/en/master/develop.html

Docs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/

Docs: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Docs: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks

Docs: http://docutils.sourceforge.net/docs/ref/rst/directives.html

Docs: https://docs.python.org/devguide/documenting.html#sections

Docs: http://sphinx-doc.org/markup/index.html

Docs: http://sphinx-doc.org/glossary.html

Articles & Presentations

Documenting Your Project With Sphinx: Exercises for the Sphinx Tutorial that Brandon Rhodes often gives at PyCon.

Extensions

Source: git https://github.com/sphinx-doc/sphinx/tree/master/sphinx/ext

Source: hg https://bitbucket.org/birkenfeld/sphinx-contrib

Docs: https://www.sphinx-doc.org/en/master/extensions.html

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

Docs: https://www.sphinx-doc.org/en/master/extdev/appapi.html

breathe: ReStructuredText and Sphinx bridge to Doxygen.
javasphinx: Sphinx extension for documenting Java projects.
numpydoc: NumPy's Sphinx extensions.
Releases: A Sphinx changelog-generating extension.
sphinx-autodoc-annotation: Use Python 3 annotations in sphinx-enabled docstrings.
sphinx-autodoc-typehints: Type hints support for the Sphinx autodoc extension
sphinx-fortran-extension: A Fortran domain and autodocumentation module for Sphinx.
sphinx-git: git Changelog for Sphinx.
sphinx-jekyll-builder: sphinx builder that outputs jekyll compatible markdown files with frontmatter
sphinx-markdown-builder: Sphinx builder that outputs markdown files.
Sphinx-prompt: Sphinx directive to add unselectable prompt.
Sphinx-pyreverse: Simple sphinx wrapper around pyreverse (from pylint suit) to generate UML diagramms from modules.
sphinxcontrib-autojs: The auto JavaScript documentation Sphinx extension.
sphinxcontrib-autoprogram: Provides an automated way to document CLI programs.
sphinxcontrib-blockdiag: Sphinx extension for embedding blockdiag diagrams.
sphinxcontrib-cldomain: Common Lisp domain for Sphinx.
sphinxcontrib-docbookrestapi: Sphinx extension that generates documentation for api-site from RST files.
sphinxcontrib-fulltoc: Extension for Sphinx to make the sidebar show a full table of contents instead of just the local headings.
sphinxcontrib-httpdomain: Provides a Sphinx domain for describing RESTful HTTP APIs. Also supports reflection for Flask, Bottle, and Tornado apps.
cornice.ext.sphinxext: Sphinx extension to build RESTful HTTP API documentation from Pyramid Cornice docstrings.
sphinxcontrib-programoutput: Sphinx extension to include program output into documents.
sphinxcontrib-napoleon: Napoleon is a pre-processor that parses NumPy and Google style docstrings.
Tut: Tut is a tool that helps you write tutorial style documentation using Sphinx.
Hieroglyph: Hieroglyph is an extension for Sphinx which builds HTML slides from ReStructuredText documents.
Sphinx-Needs: Sphinx-Needs allows the definition, linking, and filtering of need-objects: requirements, specifications, implementations, test cases, and more.
nbsphinx: Parse, execute, and generate output from Jupyter notebooks as HTML and LaTeX. Markdown in .ipynb is converted to RST with Pandoc. Markdown cells may contain toctree markup for generating tables of contents including .ipynb and .rst files.
Sphinxcontrib-proof: Sphinx extension to typeset definitions, theorems, proofs, etc.
Sphinxcontrib-packages: A sphinx extension to list tools installed on the machine generating the documentation (python versions, binaries, python packages, LaTeX packages, etc.). Useful to know which tools are installed on Readthedocs when writing your own extension.
sphinx-sitemap: sphinx-sitemap silently generates a sitemap for HTML builds.
sphinx-jsonschema: Turns a jsonschema into an integral part of your documentation. Useful when you want a single source for both validation and documentation of your JSON entities.
sphinx-gitstamp: Makes the git timestamp for each page available to HTML templates.

Internationalizations

sphinx-intl: Sphinx utility that make it easy to translate and to apply translation.

Miscellaneous

django-sphinxdoc: Integrate Sphinx documentation into a Django-powered website. Allows you to use your sites templates, auth and so on. Offers search via Haystack.
ome-documentation: Sphinx-based documentation for the Open Microscopy Environment.
riv.vim: ReStructured text editing extensions for Vim, GVim, MacVim; optionally with InstantRst gevent live reload.
sphinx-gui: Desktop GUI for editing Sphinx docs.
sphinx-markdown-sample: Markdown based sphinx the documentation generator sample.
tinkerer: Blog engine static HTML5 generator with categories, tags, landing page, nav sidebar, RSS powered by Sphinx and responsive Jinja templates.
ablog: ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with atom feeds, archive pages, blog sidebars, Disqus integration, Font-Awesome integration and easy GitHub Pages deploys

Themes

Docs: http://sphinx-doc.org/theming.html

Docs: http://sphinx-doc.org/templating.html

Source: git https://github.com/sphinx-doc/sphinx/tree/master/sphinx/themes

Alabaster: Modified Kr Sphinx doc theme.
flask-sphinx-themes: Sphinx Themes for Flask related projects and Flask itself.
krTheme Sphinx Style: Sphinx theme Kenneth Reitz uses for most projects e.g. Requests.
Sphinx Readable Theme: A clean and readable Sphinx theme with focus on autodoc – documentation from docstrings.
sphinx-better-theme: A theme for Sphinx that looks nice, is easy to style with CSS, works well on small screens and mobile devices, and organizes the page better.
sphinx_rtd_theme: Sphinx theme for readthedocs.io.
sphinx-theme-graphite: A slightly muted light-on-dark theme for the Sphinx document generator using only CSS.
sphinxjp.themes.basicstrap: Sphinx theme built with responsive Bootstrap.
sublee-sphinx-themes: Sphinx themes Heungsub Lee uses for his projects e.g. Energy, Korean, Ranking, TrueSkill.
sphinx-py3doc-enhanced-theme: A theme based on the theme of https://docs.python.org/3/ with some responsive enhancements.
sphinx-bootstrap-theme: Integrates Bootstrap CSS/Javascript framework responsive design with any Bootswatch CSS themes.
sphinx-foundation-theme: Theme based on the Foundation 4 CSS framework.
sphinx-nameko-theme: Forked from Sphinx Readable Theme, combined with elements of the Read The Docs theme.
sphinx-guzzle-theme: Sphinx theme used by Guzzle: http://guzzlephp.org
sphinx-hbp-theme: HumanBrainProject Collaboratory Sphinx Theme.
crate-docs-theme: This project provides a Sphinx theme for Crate's documentation that is compatible with ReadTheDocs.
solar-theme: Solar is an attempt to create a theme for the Python Sphinx documentation generator based on the Solarized color scheme.
sphinxtrap-theme: Sphinxtrap is a minimalist bootstrap2-based + fontawesome sphinx theme.
mdn-sphinx-theme: This is a version of the Mozilla Developer Network theme, for the Sphinx documentation engine.
sphinx_adc_theme: The Apple Developer Connection theme for sphinx

Publication

Read the Docs: Read the Docs hosts documentation, making it fully searchable and easy to find. You can import your docs using any major version control system, including Mercurial, Git, Subversion, and Bazaar. It supports webhooks so your docs get built when you commit code. There's also support for versioning so you can build docs from tags and branches of your code in your repository. A full list of features is available.
Okydoky: Automated docs builder using Sphinx/GitHub/Distribute for private use.
sphinx-autobuild: Watch a Sphinx directory and rebuild the documentation when a change is detected.
sphinx-server: A universal Sphinx Server based on sphinx-autobuild with Docker support that can be used in production (self-hosted) and for documentation development, bundled with PlantUML, Graphviz and HTTP authentication.
sphinx-me: Wraps your README-only projects in a dynamic Sphinx shell for hosting on Read the Docs.
Sphinx to GitHub: Script to prepare Sphinx html output for GitHub Pages.
ghp-import: Script to overwrite a gh-pages/master branch with a .nojekyll file for GitHub Pages.

Comments

add sphinx-autodoc-napoleon-typehints

This is a fork of the already mentioned sphinx-autodoc-typehints that additionally support google and numpy style docstrings making it somewhat more versatile and seems to be the only possibility I have found to work with type annotations AND google/numpy style docstrings.

opened by daviskirk 3
DOC: README.rst: | Homepage,Source,Docs,Wikipedia:
The GitHub edit preview renders these line-blocks_ "| " without newlines, but this pattern for listing (attribute, values) seems to work okay.

| Wikipedia: `<URI(withparens)>`__ | Homepage: http://sphinx-doc.org/ | Source: git https://github.com/sphinx-doc/sphinx

.. _line-blocks: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#line-blocks .. _python devguide heading section character guidelines docs: https://docs.python.org/devguide/documenting.html#sections
opened by westurner 2
I would like to contribute.

I would like to help with this list. I just created an awesome-restructuredtext list but it occured to me that a list might exist for sphinxdoc. I'm not sure if i should simply add to your list, or have a separate list, since sphinx is not the focus of my list.

I also noted that there are outstanding pull requests. let me know how I can help.

opened by kaymccormick 1
Add sphinx-server

Add Sphinx-Server, a Docker-based lightweight configurable server that can be used to host, build and share documentation with authentication, PlantUML and Graphviz support.

opened by quentinus95 1
Add sphinxcontrib-constdata

I think this extension is awesome because it decouple documentation and external constant data like UI labels, keyboard shortcuts, etc., used in any large application’s docs.

Devs and translators often change these strings. Idea of hard-coding these strings in the docs, and manually watching changes and updating them across the docs, scared me so much that I developed this Sphinx extension. The extension includes even translation of these constdata data to support multilingual docs.

Read more at https://documatt.gitlab.io/sphinxcontrib-constdata/

opened by mattwarrick 2
Add docx builder extension
docxsphinx is awesome because...

It builds Sphinx projects to Microsoft Word (docx) files, therefore promotes compatibility with a proprietary tool.

Allows to configure a custom stylesheet in the docx or dotx format.

The project is up to date, i.e. actively developed. However, it's possible that it doesn't support the complete set of Sphinx markup yet.

As a technical writer with 14 years of experience, I'm using it in my work and I'd love to support further use and development.
opened by Lennonka 0
Thoughts on linking directly to sphinx-themes.org?

Hi there! I'm working to revamp https://sphinx-themes.org (see under-development v2: https://sphinx-themes.github.io/sphinx-themes.org/), a website intended as a showcase of Sphinx documentation themes.

This repository is also maintaining a list of Sphinx themes, which feels like duplicated effort and I'd like to suggest linking directly to https://sphinx-themes.org (which will be updated to the new design soon).

opened by pradyunsg 2
Theme: cloud

Just came across this Cloud Sphinx Theme, which is one of the best themes I've seen: https://cloud-sptheme.readthedocs.io/

Example of it being used by a popular project: https://xon.sh/contents.html

Also looks to be somewhat well-maintained; created in 2011, latest update is May 2020: https://cloud-sptheme.readthedocs.io/en/latest/history.html

opened by dannguyen 0
Add sphinx_reredirects extension

It is the extension for managing redirects with client-side HTML files containing meta refresh tags. Many static file hosting doesn't support redirects, and to prevent 404 if page is moved or renamed, the client-side redirect are the only option. The extension supports wildcards and has configurable HTML file template.

DISCLAIMER: I'm author of the extension.
immature

opened by mattwarrick 2