https://github.com/readthedocs-examples/example-sphinx-basic

A basic Sphinx project for Read the Docs
https://github.com/readthedocs-examples/example-sphinx-basic

example-project sphinx-doc

Last synced: about 1 year ago
JSON representation

A basic Sphinx project for Read the Docs

• Host: GitHub
• URL: https://github.com/readthedocs-examples/example-sphinx-basic
• Owner: readthedocs-examples
• License: mit
• Created: 2022-06-22T11:10:13.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2023-08-18T07:42:59.000Z (almost 3 years ago)
• Last Synced: 2025-05-31T11:37:21.274Z (about 1 year ago)
• Topics: example-project, sphinx-doc
• Language: Python
• Homepage: https://example-sphinx-basic.readthedocs.io/
• Size: 29.3 KB
• Stars: 26
• Watchers: 3
• Forks: 125
• Open Issues: 0
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
Example: Basic Sphinx project for Read the Docs

===============================================

.. image:: https://readthedocs.org/projects/example-sphinx-basic/badge/?version=latest

    :target: https://example-sphinx-basic.readthedocs.io/en/latest/?badge=latest

    :alt: Documentation Status

.. This README.rst should work on Github and is also included in the Sphinx documentation project in docs/ - therefore, README.rst uses absolute links for most things so it renders properly on GitHub

This example shows 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/``. All the ``*.rst`` make up sections in the documentation.

⚙️ `.readthedocs.yaml `_

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

⚙️ `docs/conf.py `_

    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 `_). Make sure to add your Python dependencies to ``requirements.txt`` or if you choose `pip-tools `_, edit ``docs/requirements.in`` and remember to run ``pip-compile docs/requirements.in``.

💡 `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 `_.

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 `_:

.. code-block:: console

    # 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``:

.. code-block:: console

    # 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:

#. place your ``docs/`` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration.

#. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs

#. copy ``.readthedocs.yaml`` and the ``docs/`` folder into your project.

#. customize all the files, replacing example contents.

#. add your own Python project, replacing the ``pyproject.toml`` configuration and ``lumache.py`` module.

#. rebuild the documenation locally to see that it works.

#. *finally*, 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.