Example: Basic Sphinx project for Read the Docs

Documentation Status

This example shows the an integration of a basic Sphinx project with Read the Docs. You’re encouraged to view it to get inspiration and copy & paste from the files in the source code. If you are using Read the Docs for the first time, have a look at the official Read the Docs Tutorial.

📚 docs/

A basic Sphinx project lives in docs/, it was generated using Sphinx defaults. All the *.rst make up sections in the documentation.

⚙️ .readthedocs.yaml

Read the Docs Build configuration is stored in .readthedocs.yaml.

📍 docs/requirements.txt and docs/requirements.in

Python dependencies are pinned (uses pip-tools).

💡 docs/api.rst

By adding our example Python module lumache in the reStructuredText directive :autosummary:, Sphinx will automatically scan this module and generate API docs.

💡 docs/usage.rst

Sphinx can automatically extract API documentation directly from Python modules, using for instance the :autofunction: directive.

💡 lumache.py

API docs are generated for this example Python module - they use docstrings directly in the documentation, notice how this shows up in the rendered documentation.

🔢 Git tags versioning

We use a basic versioning mechanism by adding a git tag for every release of the example project. All releases and their version numbers are visible on example-sphinx-basic.readthedocs.io.

📜 README.rst

Contents of this README.rst are visible on Github and included on the documentation index page (Don’t Repeat Yourself).

⁉️ Questions / comments

If you have questions related to this example, feel free to can ask them as a Github issue here.

Sphinx Example Project usage

This project has a standard Sphinx layout which is built by Read the Docs almost the same way that you would build it locally (on your own laptop!).

You can build and view this documentation project locally - we recommend that you activate a local Python virtual environment first:

# 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 . _build/

You can also build the documentation locally with make:

# Enter the Sphinx project
cd docs/

# Build with make
make html

# Open with your preferred browser, pointing it to the documentation index page
firefox _build/html/index.html

Using the example in your own project

If you are new to Read the Docs, you may want to refer to the Read the Docs User documentation.

If you are copying this code in order to get started with your documentation, you need to:

  • Create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs

  • Customize all docs/*.rst files

  • Add your own Python project, replacing the pyproject.toml configuration and lumache.py module.

  • Rebuild the documenation locally to see that it works.

  • Register your project on Read the Docs, see Importing Your Documentation.

Read the Docs tutorial

To get started with Read the Docs, you may also refer to the Read the Docs tutorial. It provides a full walk-through of building an example project similar to the one in this repository.

Welcome to Lumache’s documentation!

Lumache (/lu’make/) is a Python library for cooks and food lovers that creates recipes mixing random ingredients. It pulls data from the Open Food Facts database and offers a simple and intuitive API.

Check out the Usage section for further information, including how to Installation the project.


This project is under active development.