|
| 1 | +Example: Basic Sphinx project for Read the Docs |
| 2 | +=============================================== |
| 3 | + |
| 4 | +.. image:: https://readthedocs.org/projects/example-sphinx-basic/badge/?version=latest |
| 5 | + :target: https://example-sphinx-basic.readthedocs.io/en/latest/?badge=latest |
| 6 | + :alt: Documentation Status |
| 7 | + |
| 8 | +.. 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 |
| 9 | +
|
| 10 | +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 <https://docs.readthedocs.io/en/stable/tutorial/index.html>`__. |
| 11 | + |
| 12 | +📚 `docs/ <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/>`_ |
| 13 | + A basic Sphinx project lives in ``docs/``. All the ``*.rst`` make up sections in the documentation. |
| 14 | +⚙️ `.readthedocs.yaml <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/.readthedocs.yaml>`_ |
| 15 | + Read the Docs Build configuration is stored in ``.readthedocs.yaml``. |
| 16 | +⚙️ `docs/conf.py <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/conf.py>`_ |
| 17 | + Both the configuration and the folder layout follow Sphinx default conventions. You can change the `Sphinx configuration values <https://www.sphinx-doc.org/en/master/usage/configuration.html>`_ in this file |
| 18 | +📍 `docs/requirements.txt <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.txt>`_ and `docs/requirements.in <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/requirements.in>`_ |
| 19 | + Python dependencies are `pinned <https://docs.readthedocs.io/en/latest/guides/reproducible-builds.html>`_ (uses `pip-tools <https://pip-tools.readthedocs.io/en/latest/>`_). Make sure to add your Python dependencies to ``requirements.txt`` or if you choose `pip-tools <https://pip-tools.readthedocs.io/en/latest/>`_, edit ``docs/requirements.in`` and remember to run ``pip-compile docs/requirements.in``. |
| 20 | +💡 `docs/api.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/api.rst>`_ |
| 21 | + By adding our example Python module ``lumache`` in the reStructuredText directive ``:autosummary:``, Sphinx will automatically scan this module and generate API docs. |
| 22 | +💡 `docs/usage.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/docs/usage.rst>`_ |
| 23 | + Sphinx can automatically extract API documentation directly from Python modules, using for instance the ``:autofunction:`` directive. |
| 24 | +💡 `lumache.py <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/lumache.py>`_ |
| 25 | + 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. |
| 26 | +🔢 Git tags versioning |
| 27 | + 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 <https://example-sphinx-basic.readthedocs.io/en/latest/>`__. |
| 28 | +📜 `README.rst <https://github.com/readthedocs-examples/example-sphinx-basic/blob/main/README.rst>`_ |
| 29 | + Contents of this ``README.rst`` are visible on Github and included on `the documentation index page <https://example-sphinx-basic.readthedocs.io/en/latest/>`_ (Don't Repeat Yourself). |
| 30 | +⁉️ Questions / comments |
| 31 | + If you have questions related to this example, feel free to can ask them as a Github issue `here <https://github.com/readthedocs-examples/example-sphinx-basic/issues>`_. |
| 32 | + |
| 33 | + |
| 34 | +Example Project usage |
| 35 | +--------------------- |
| 36 | + |
| 37 | +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!). |
| 38 | + |
| 39 | +You can build and view this documentation project locally - we recommend that you activate `a local Python virtual environment first <https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment>`_: |
| 40 | + |
| 41 | +.. code-block:: console |
| 42 | +
|
| 43 | + # Install required Python dependencies (Sphinx etc.) |
| 44 | + pip install -r docs/requirements.txt |
| 45 | +
|
| 46 | + # Enter the Sphinx project |
| 47 | + cd docs/ |
| 48 | + |
| 49 | + # Run the raw sphinx-build command |
| 50 | + sphinx-build -M html . _build/ |
| 51 | +
|
| 52 | +
|
| 53 | +You can also build the documentation locally with ``make``: |
| 54 | + |
| 55 | +.. code-block:: console |
| 56 | +
|
| 57 | + # Enter the Sphinx project |
| 58 | + cd docs/ |
| 59 | + |
| 60 | + # Build with make |
| 61 | + make html |
| 62 | + |
| 63 | + # Open with your preferred browser, pointing it to the documentation index page |
| 64 | + firefox _build/html/index.html |
| 65 | +
|
| 66 | +
|
| 67 | +Using the example in your own project |
| 68 | +------------------------------------- |
| 69 | + |
| 70 | +If you are new to Read the Docs, you may want to refer to the `Read the Docs User documentation <https://docs.readthedocs.io/>`_. |
| 71 | + |
| 72 | +If you are copying this code in order to get started with your documentation, you need to: |
| 73 | + |
| 74 | +#. place your ``docs/`` folder alongside your Python project. If you are starting a new project, you can adapt the `pyproject.toml` example configuration. |
| 75 | +#. use your existing project repository or create a new repository on Github, GitLab, Bitbucket or another host supported by Read the Docs |
| 76 | +#. copy ``.readthedocs.yaml`` and the ``docs/`` folder into your project. |
| 77 | +#. customize all the files, replacing example contents. |
| 78 | +#. add your own Python project, replacing the ``pyproject.toml`` configuration and ``lumache.py`` module. |
| 79 | +#. rebuild the documenation locally to see that it works. |
| 80 | +#. *finally*, register your project on Read the Docs, see `Importing Your Documentation <https://docs.readthedocs.io/en/stable/intro/import-guide.html>`_. |
| 81 | + |
| 82 | + |
| 83 | +Read the Docs tutorial |
| 84 | +---------------------- |
| 85 | + |
| 86 | +To get started with Read the Docs, you may also refer to the `Read the Docs tutorial <https://docs.readthedocs.io/en/stable/tutorial/>`__. |
| 87 | +It provides a full walk-through of building an example project similar to the one in this repository. |
0 commit comments