🌐
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 - I have designed and created a framework, tkinter_spa. And it was a very good opportunity for me to set documentation up from scratch, with my own conventions and applying my own philosophy. I will share with you what I learnt during the documentation of my Python framework thanks to sphinx.
🌐
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 ...
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
🌐
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.
🌐
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
Enter Sphinx: Sphinx is a tool that can automatically generate documentation in various formats (html, pdf, etc) based on the docstrings in your code. Popular examples for documentation pages that have been built with Sphinx, are scikit-learn or scikit-image.
Starred by 23 users
Forked by 34 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 ·
🌐
Sphinx
sphinx-doc.org › en › master › usage › domains › python.html
The Python Domain — Sphinx documentation
The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default). ... Reference a Python decorator; dotted names may be used. The rendered output will be prepended with an at-sign (@), for example: :py:deco:`removename` produces @removename.
🌐
Towards Data Science
towardsdatascience.com › home › latest › documenting python code with sphinx
Documenting Python code with Sphinx | Towards Data Science
March 5, 2025 - In simplest terms, the sphinx takes in your .rst files and converts them to HTML, and all that is done using just a bunch of commands! Major Python libraries like Django, NumPy, SciPy, Scikit-Learn, Matplotlib, and many more are written using Sphinx.
🌐
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: