diff --git a/docs/changes.rst b/docs/changes.rst index 452242279..aac1e6031 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -13,6 +13,8 @@ Pending class instance, regardless if any data was generated. * Fixed selenium tests for CI by using psycopg for Python 3.13 runs. * Added ``CommunityPanel`` containing links to documentation and resources. +* Added how to generate the documentation locally to the contributing + documentation. 6.0.0 (2025-07-22) ------------------ diff --git a/docs/contributing.rst b/docs/contributing.rst index 9259750c2..6377e59ea 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -12,6 +12,8 @@ You can report bugs and request features in the `bug tracker Please search the existing database for duplicates before filing an issue. +.. _code: + Code ---- @@ -207,3 +209,60 @@ The release itself requires the following steps: #. **After the publishing completed** edit the automatically created GitHub release to include the release notes (you may use GitHub's "Generate release notes" button for this). + + +Building the documentation locally +---------------------------------- + +The project's documentation is built using `Sphinx `_. +You can generate it locally to preview your changes before submitting a pull +request. + + +Prerequisites +-------------- + +Before building the documentation, ensure that all dependencies are installed +as described in :ref:`the setup instructions `. + + + +Using Tox (Cross-Platform) +------------------------------------ + +To build the documentation using Tox, run from the project root: + +.. code-block:: bash + + tox -e docs -- html + +This will generate the HTML files in ``docs/_build/html/``. + +You can then open the documentation in your browser: + +- **Linux:** ``xdg-open docs/_build/html/index.html`` +- **macOS:** ``open docs/_build/html/index.html`` +- **Windows:** ``start docs\_build\html\index.html`` + +*Tox automatically installs the necessary dependencies, so you don’t need +to activate a virtual environment manually.* + + +Troubleshooting +---------------- + + +If you encounter an error about a missing dependency such as +``sphinx-build: command not found``, ensure that your virtual environment is +activated and all dependencies are installed: + +.. code-block:: bash + + pip install -r requirements_dev.txt + +Alternatively, you can build the documentation using Tox, which automatically +handles dependencies and environment setup: + +.. code-block:: bash + + tox -e docs -- html