🌐
Sphinx
sphinx-doc.org › en › master › usage › quickstart.html
Getting started — Sphinx documentation
For example, to document Python’s built-in function enumerate(), you would add this to one of your source files.
🌐
Medium
wbarillon.medium.com › sphinx-documentation-with-professional-standards-25e5683cb38b
Sphinx documentation with professional standards | by Will Barillon | Medium
February 12, 2026 - In this article, I share my perspective and conventions on documentating with the Python library sphinx.
Discussions

Which projects or sites make the best use of Sphinx documentation?
Flask has one of best documentations Sphinx generates. LEPL also could be a good example of Sphinx documentation. jDoctest is not a Python project, but it uses Sphinx also and its theme is beautiful. More on reddit.com
🌐 r/Python
22
8
January 2, 2011
How to use Python to programmatically generate part of Sphinx documentation? - Stack Overflow
In this project, I describe a list ... for example: Copycommands = {"copy" : "Copy the highlighted text in the clipboard", "paste" : "Paste the clipboard text to cursor location", ...} What I would like to know, is if there is a method in sphinx to load the yaml file during the make html cycle, translate the python dictionary ... More on stackoverflow.com
🌐 stackoverflow.com
Sphinx Docs Translation: tutorial and template : r/Python
News about the programming language Python. If you have something to teach others post here. If you have questions or are a newbie use r/learnpython More on reddit.com
🌐 r/Python
Sphinx vs mkdocs vs (your favorite Pythonic Doc Tool)
Material for MkDocs . You're welcome. More on reddit.com
🌐 r/Python
35
61
April 9, 2025
🌐
Readthedocs
example-sphinx-basic.readthedocs.io
Example: Basic Sphinx project for Read the Docs — Basic Sphinx Example Project documentation
# Install required Python dependencies (Sphinx etc.) pip install -r docs/requirements.txt # Enter the Sphinx project cd docs/ # Run the raw sphinx-build command sphinx-build -M html .
🌐
Sphinx
sphinx-doc.org › en › master › examples.html
Projects using Sphinx — Sphinx documentation
Read the Docs, a software-as-a-service documentation hosting platform, uses Sphinx to automatically build documentation updates that are pushed to GitHub. Spyder, the Scientific Python Development Environment, uses Sphinx in its help pane to render rich documentation for functions, classes and methods automatically or on-demand.
documentation generator which converts reStructuredText files into HTML
Documentation Status
Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments. Sphinx converts reStructuredText files into HTML websites and other … Wikipedia
Factsheet
Developers Georg Brandl, Adam Turner
Release March 21, 2008
Stable release 9.1.0
/ 31 December 2025; 8 months ago
Factsheet
Developers Georg Brandl, Adam Turner
Release March 21, 2008
Stable release 9.1.0
/ 31 December 2025; 8 months ago
🌐
Sphinx
sphinx-doc.org
Sphinx — Sphinx documentation
Generate API documentation for Python, C++ and other software domains, manually or automatically from docstrings, ensuring your code documentation stays up-to-date with minimal effort. ... Add documentation translations multiple languages to reach a global audience. ... Benefit from an active community, with numerous resources, tutorials, forums, and examples. ... See below for how to navigate Sphinx...
🌐
GitHub
github.com › melissawm › minimalsphinx
GitHub - melissawm/minimalsphinx: A repo with a minimal Sphinx example for Python documentation. · GitHub
This repo contains a very simple example of how to set up and use Sphinx to generate Python documentation.
Author: melissawm
Find elsewhere
🌐
Woolsey Workshop
woolseyworkshop.com › home › documenting python programs with sphinx
Documenting Python Programs With Sphinx - Woolsey Workshop
April 27, 2023 - Create a project directory named MySphinxExample and go into that directory. Create a src directory under the project directory and go into that directory as well. This is where we will place our source code.
🌐
Samposium
samnicholls.net › 2016 › 06 › 15 › how-to-sphinx-readthedocs
An idiot’s guide to Python documentation with Sphinx and ReadTheDocs
January 17, 2018 - Napoleon for example was, sphinxcontrib.napoleon and sphinxcontrib-napoleon, respectively. ↩ · Update I’m told that this could be because I said yes to the first option of sphinx-quickstart on whether to separate source and build, meaning I need to use the source directory for apidoc.[^5] ↩ · autodoc, config, docstring, documentation, napoleon, numpy, py-modindex, python, readthedocs, sphinx, sphinx-autodoc, sphinx-napoleon, theme
🌐
Write the Docs
writethedocs.org › guide › tools › sphinx
Introduction to Sphinx — Write the Docs
In particular, it is extensible: ... sophisticated parsing. For example, Sphinx includes directives to relate documentation of modules, classes and methods to the corresponding code. The first step to getting going is installing Sphinx.
🌐
GitHub
github.com › timstaley › sphinx-example
GitHub - timstaley/sphinx-example: A mini-tutorial / cheatsheet / link-collection to get you started documenting Python code using Sphinx. · GitHub
A mini-tutorial / working example / cheatsheet / link-collection to get you started documenting Python code using the Sphinx documentation system.
Starred by 34 users
Forked by 51 users
Languages: Python
🌐
Sphinx-themes
sphinx-themes.org
Sphinx Themes Gallery
Python Documentation click image to see more · Readable click image to see more · Redactor click image to see more · Renku click image to see more · Sandstone click image to see more · Sizzle click image to see more · Solar click image to see more · Stanford click image to see more ·
🌐
Docslikecode
docslikecode.com › learn › 01-sphinx-python-rtd
Set Up Sphinx with Python | Let’s Treat Docs Like Code
April 11, 2026 - Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from ReStructured text files.
🌐
Sphinx
sphinx-doc.org › en › master › tutorial › index.html
Build your first project — Sphinx documentation
Several other languages are natively supported in Sphinx for manual code documentation, however they require extensions for automatic code documentation, like Breathe. To follow the instructions you will need access to a Linux-like command line and a basic understanding of how it works, as well as a working Python installation for development, since you will use Python virtual environments to create the project.
🌐
Medium
medium.com › @pratikdomadiya123 › build-project-documentation-quickly-with-the-sphinx-python-2a9732b66594
Build project documentation quickly with the Sphinx Python … | by pratik domadiya | Medium
January 13, 2024 - So far, your documentation folder includes an index.rst file serving as the main landing page. However, we have yet to generate the project-folder.rst file, which contains our actual Python project code. Go to the root folder (sphinx-demo).
Top answer
1 of 7
27

At the end I find a way to achieve what I wanted. Here's the how-to:

  1. Create a python script (let's call it generate-includes.py) that will generate the reStructuredText and save it in the myrst.inc file. (In my example, this would be the script loading and parsing the YAML, but this is irrelevant). Make sure this file is executable!!!
  2. Use the include directive in your main .rst document of your documentation, in the point where you want your dynamically-generated documentation to be inserted:

    .. include:: myrst.inc
    
  3. Modify the sphinx Makefile in order to generate the required .inc files at build time:

    myrst.inc:
        ./generate-includes.py
    
    html: myrst.inc
        ...(other stuff here)
    
  4. Build your documentation normally with make html.

2 of 7
19

An improvement based on Michael's code and the built-in include directive:

import sys
from os.path import basename

try:
    from StringIO import StringIO
except ImportError:
    from io import StringIO

from docutils.parsers.rst import Directive    
from docutils import nodes, statemachine

class ExecDirective(Directive):
    """Execute the specified python code and insert the output into the document"""
    has_content = True

    def run(self):
        oldStdout, sys.stdout = sys.stdout, StringIO()

        tab_width = self.options.get('tab-width', self.state.document.settings.tab_width)
        source = self.state_machine.input_lines.source(self.lineno - self.state_machine.input_offset - 1)

        try:
            exec('\n'.join(self.content))
            text = sys.stdout.getvalue()
            lines = statemachine.string2lines(text, tab_width, convert_whitespace=True)
            self.state_machine.insert_input(lines, source)
            return []
        except Exception:
            return [nodes.error(None, nodes.paragraph(text = "Unable to execute python code at %s:%d:" % (basename(source), self.lineno)), nodes.paragraph(text = str(sys.exc_info()[1])))]
        finally:
            sys.stdout = oldStdout

def setup(app):
    app.add_directive('exec', ExecDirective)

This one imports the output earlier so that it goes straight through the parser. It also works in Python 3.

🌐
Biapol
biapol.github.io › blog › johannes_mueller › entry_sphinx › Readme.html
Automated package documentation with Sphinx — BiA-PoL blog
In order to add module submodule_a from our example repository to the documentation pages, add the automodule extension as a directive to index.rst. By setting the option :imported-members:, we tell Sphinx to also document all the functions of submodule_a, that have been made public in __init__.py:
Starred by 23 users
Forked by 34 users
Languages: Python
🌐
Sphinx-gallery
sphinx-gallery.github.io › stable › syntax.html
Structuring Python scripts for Sphinx-Gallery — Sphinx-Gallery 0.21.0-git documentation
This functionality can be helpful when writing a Sphinx-Gallery .py example as the blocks allow you to easily create pairs of subsequent Sphinx-Gallery text and code blocks. Here are the contents of an example Python file using the ‘code block’ functionality:
🌐
Readthedocs
sphinx-tutorial.readthedocs.io › start
Getting Started: Overview & Installing Initial Project — Sphinx Tutorial 1.0 documentation
This should run Sphinx in your shell, and output HTML. At the end, it should say something about the documents being ready in _build/html. You can now open them in your browser by typing: ... # Inside docs/_build/html directory. python -m SimpleHTTPServer # For python 3 python3 -m http.server