From 3ce6cf9a1f82d558e200e957438eeb4cbec7beab Mon Sep 17 00:00:00 2001 From: okot daniel Date: Thu, 9 Oct 2025 20:18:34 +0300 Subject: [PATCH 1/9] docs: added documentation on how to generate docs locally --- docs/contributing.rst | 74 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index 9259750c2..045e10062 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,75 @@ 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. + +Two main approaches are supported: + +- **Make** – recommended for Linux/macOS users. +- **Tox** – recommended for Windows users or for isolated, consistent builds. + +Prerequisites +-------------- + +Before building the documentation, ensure that all dependencies are installed as described in +:ref:`the setup instructions `. +If you plan to use *Tox*, make sure it is installed: + +.. code-block:: bash + + pip install tox + + +Option 1: Using Make (Linux/macOS) +---------------------------------- + +From the project root, run: + +.. code-block:: bash + + cd docs/ + make html + +After the build completes, open the generated documentation: + +- **macOS:** ``open _build/html/index.html`` +- **Linux:** ``xdg-open _build/html/index.html`` + + +Option 2: 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: + +- **macOS:** ``open docs/_build/html/index.html`` +- **Linux:** ``xdg-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 such as ``make: sphinx-build: Command not found``, install Sphinx manually: + + .. code-block:: bash + + pip install sphinx + +- If HTML files are not generated, review the build output for warnings or errors. +- On Windows, if ``make`` is unavailable, use the Tox approach instead. From dd1d84eb00cee520e093736843e2c4cae3d1c956 Mon Sep 17 00:00:00 2001 From: okot daniel Date: Thu, 9 Oct 2025 22:00:31 +0300 Subject: [PATCH 2/9] docs: added documentation on how to generate docs locally --- docs/changes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/changes.rst b/docs/changes.rst index 452242279..38b87328d 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -13,6 +13,7 @@ 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) ------------------ From e225317063a89da6a2979918168a5553f0720eac Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Thu, 9 Oct 2025 19:14:44 +0000 Subject: [PATCH 3/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 045e10062..d8d80c669 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -226,7 +226,7 @@ Prerequisites -------------- Before building the documentation, ensure that all dependencies are installed as described in -:ref:`the setup instructions `. +:ref:`the setup instructions `. If you plan to use *Tox*, make sure it is installed: .. code-block:: bash From d9d0be8983c4992efac5b72b6851fe3fb10dc92c Mon Sep 17 00:00:00 2001 From: Okot Daniel Date: Fri, 10 Oct 2025 11:16:34 +0300 Subject: [PATCH 4/9] Update docs/contributing.rst Co-authored-by: Tim Schilling --- docs/contributing.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index d8d80c669..3ab0f84b4 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -263,8 +263,7 @@ This will generate the HTML files in ``docs/_build/html/``. You can then open the documentation in your browser: -- **macOS:** ``open docs/_build/html/index.html`` -- **Linux:** ``xdg-open docs/_build/html/index.html`` +- **macOS & Linux:** ``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.* From 71d81bc3f19daad6c51ec9fbd45ee729eb291710 Mon Sep 17 00:00:00 2001 From: okot daniel Date: Fri, 10 Oct 2025 13:12:22 +0300 Subject: [PATCH 5/9] docs: modified troubleshooting section on how to generate docs locally --- docs/contributing.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 3ab0f84b4..67d912aea 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -227,11 +227,7 @@ Prerequisites Before building the documentation, ensure that all dependencies are installed as described in :ref:`the setup instructions `. -If you plan to use *Tox*, make sure it is installed: -.. code-block:: bash - - pip install tox Option 1: Using Make (Linux/macOS) @@ -272,11 +268,17 @@ You can then open the documentation in your browser: Troubleshooting ---------------- -- If you encounter an error such as ``make: sphinx-build: Command not found``, install Sphinx manually: - .. code-block:: bash +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 sphinx + pip install -r requirements_dev.txt + +Alternatively, you can build the documentation using Tox, which automatically handles +dependencies and environment setup: + +.. code-block:: bash -- If HTML files are not generated, review the build output for warnings or errors. -- On Windows, if ``make`` is unavailable, use the Tox approach instead. + tox -e docs -- html \ No newline at end of file From 91a757135a41f12a79b12abb55027336c9627509 Mon Sep 17 00:00:00 2001 From: okot daniel Date: Fri, 10 Oct 2025 13:53:31 +0300 Subject: [PATCH 6/9] docs: modified troubleshooting section on how to generate docs locally --- docs/contributing.rst | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 67d912aea..6d7db3ed7 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -217,10 +217,6 @@ 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. -Two main approaches are supported: - -- **Make** – recommended for Linux/macOS users. -- **Tox** – recommended for Windows users or for isolated, consistent builds. Prerequisites -------------- @@ -230,23 +226,7 @@ Before building the documentation, ensure that all dependencies are installed as -Option 1: Using Make (Linux/macOS) ----------------------------------- - -From the project root, run: - -.. code-block:: bash - - cd docs/ - make html - -After the build completes, open the generated documentation: - -- **macOS:** ``open _build/html/index.html`` -- **Linux:** ``xdg-open _build/html/index.html`` - - -Option 2: Using Tox (Cross-Platform) +Using Tox (Cross-Platform) ------------------------------------ To build the documentation using Tox, run from the project root: From 3119b5ea2a445873cb909df1f6a0b9cec7ade6ed Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 10 Oct 2025 10:54:37 +0000 Subject: [PATCH 7/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 6d7db3ed7..aebb4939d 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -261,4 +261,4 @@ dependencies and environment setup: .. code-block:: bash - tox -e docs -- html \ No newline at end of file + tox -e docs -- html From 9bd2078c32cce25ce09df9370c6f4fe42cfbb4b6 Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Fri, 10 Oct 2025 09:24:20 -0500 Subject: [PATCH 8/9] Adjust the new docs line lengths to be within limits. --- docs/changes.rst | 3 ++- docs/contributing.rst | 19 +++++++++++-------- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/changes.rst b/docs/changes.rst index 38b87328d..aac1e6031 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -13,7 +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. +* 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 aebb4939d..1ca987ef9 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -215,14 +215,15 @@ 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. +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 `. +Before building the documentation, ensure that all dependencies are installed +as described in :ref:`the setup instructions `. @@ -242,22 +243,24 @@ You can then open the documentation in your browser: - **macOS & Linux:** ``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.* +*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: +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: +Alternatively, you can build the documentation using Tox, which automatically +handles dependencies and environment setup: .. code-block:: bash From 57f9abb7fec7c398498d9f9625324afe151bf0b0 Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Fri, 10 Oct 2025 09:27:36 -0500 Subject: [PATCH 9/9] Revert code review suggestion of combining macOS and Linux open commands. --- docs/contributing.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 1ca987ef9..6377e59ea 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -240,7 +240,8 @@ This will generate the HTML files in ``docs/_build/html/``. You can then open the documentation in your browser: -- **macOS & Linux:** ``open docs/_build/html/index.html`` +- **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