🌐
Sphinx
sphinx-doc.org › en › master › tutorial › index.html
Build your first project — Sphinx documentation
The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals of how projects are created and structured. You will create a fictional software library to generate random food recipes that will serve as a guide throughout the process, with the objective of properly documenting it.
🌐
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
I am using Sphinx to generate the documentation for a project of mine. In this project, I describe a list of available commands in a yaml file which, once loaded, results in a dictionary in the f... 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 is killing me
Can you post an example of a function from your code that isn't being documented? More on reddit.com
🌐 r/learnpython
9
5
April 30, 2024
🌐
Docslikecode
docslikecode.com › learn › 01-sphinx-python-rtd
Set Up Sphinx with Python | Let’s Treat Docs Like Code
April 11, 2026 - With the virtual environment still activated, run sphinx-quickstart, which creates a starting project for a Sphinx documentation project. ... Answer all the questions from the prompts. You can choose enter to pick all the defaults and get a working project in the current directory (.). ... ...
🌐
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
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...
🌐
Samposium
samnicholls.net › 2016 › 06 › 15 › how-to-sphinx-readthedocs
An idiot’s guide to Python documentation with Sphinx and ReadTheDocs
January 17, 2018 - Be sure to set the -o outputdir that will contain the generated Sphinx source files to source/. This took me a while to figure out, but without it (say just dumping everything into the docs/ directory), the py-modindex.html file would not be generated when built by ReadTheDocs and would thus be missing, causing a 404 on the website3. sourcedir (which is more sensibly called module_path in the Sphinx documentation) should point to your Python package (e.g.
Find elsewhere
🌐
Woolsey Workshop
woolseyworkshop.com › home › documenting python programs with sphinx
Documenting Python Programs With Sphinx - Woolsey Workshop
April 27, 2023 - This tutorial will teach you how to use the Sphinx utility to generate program documentation for your Python based projects.
🌐
Write the Docs
writethedocs.org › guide › tools › sphinx
Introduction to Sphinx — Write the Docs
The first step to getting going is installing Sphinx. Sphinx is a Python project, so it can be installed like any other Python library.
🌐
Readthedocs
sphinx-rtd-tutorial.readthedocs.io › en › latest
A “How to” Guide for Sphinx + ReadTheDocs — Sphinx-RTD-Tutorial documentation
This document aims to describe a standard way of creating a Python package, which can be documented using Sphinx and then consequently published to ReadTheDocs, so that it’s made available to whoever needs to read it.
Starred by 3 users
Forked by 2 users
Languages: Python
🌐
Sphinx
sphinx-doc.org › en › master › usage › quickstart.html
Getting started — Sphinx documentation
The config values that you probably want to change are already put into the conf.py by sphinx-quickstart and initially commented out (with standard Python syntax: a # comments the rest of the line). To change the default value, remove the hash sign and modify the value.
🌐
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 ...
🌐
Readthedocs
example-sphinx-basic.readthedocs.io
Example: Basic Sphinx project for Read the Docs — Basic Sphinx Example Project documentation
If you are using Read the Docs for the first time, have a look at the official Read the Docs Tutorial. ... A basic Sphinx project lives in docs/. All the *.rst make up sections in the documentation. ... Read the Docs Build configuration is stored in .readthedocs.yaml. ... Both the configuration and the folder layout follow Sphinx default conventions. You can change the Sphinx configuration values in this file · 📍 docs/requirements.txt and docs/requirements.in · Python dependencies are pinned (uses pip-tools).
🌐
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
🌐
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 ·
🌐
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 - Define a folder structure as below. As you can see sphinx-demo is root dir. Inside root dir, we have 2 subfolders: one for documentation and another for your actual project folder.
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.

🌐
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.