From 71a9e69e6c1b9cbc92aae2eecb70f82f280206f5 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Tue, 11 Jun 2024 13:58:09 +0200 Subject: [PATCH] add instructions for additional Python packages to the readme Addresses #197 Signed-off-by: Ruth Fuchss --- readme.rst | 31 +++++++++++++++++++++++++++++-- 1 file changed, 29 insertions(+), 2 deletions(-) diff --git a/readme.rst b/readme.rst index 6d339b5e..ad327e18 100644 --- a/readme.rst +++ b/readme.rst @@ -87,6 +87,8 @@ pack* and *Work with your documentation* post-enablement. + `Activate/deactivate feedback button`_ + `Configure included extensions`_ + `Add custom configuration`_ + + `Add Python packages`_ + + `Add page-specific configuration`_ * `Change log`_ @@ -281,6 +283,7 @@ The following extensions will automatically be included based on the configurati - |notfound.extension|_ You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. +If the extensions need specific Python packages, add those to the ``custom_required_modules`` variable. Add custom configuration ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -294,6 +297,29 @@ The following links can help you with additional configuration: - `Sphinx extensions`_ - `Furo documentation`_ (Furo is the Sphinx theme we use as our base.) +Add Python packages +^^^^^^^^^^^^^^^^^^^ + +If you need additional Python packages for any custom processing you do in your documentation, add them to the ``custom_required_modules`` variable in ``custom_conf.py``. + +If you use these packages inside of ``custom_conf.py``, you will encounter a circular dependency (see issue `#197`_). +To work around this problem, add a step that installs the packages to the ``.readthedocs.yaml`` file: + +.. code-block:: yaml + + ... + jobs: + pre_install: + - pip install + - python3 .sphinx/build_requirements.py + ... + +In addition, override the ``ADDPREREQS`` variable in the Makefile with the names of the packages. +For example:: + + make html ADDPREREQS='' + + Add page-specific configuration ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -491,7 +517,7 @@ To run against all files with a specific extension within a folder: make vale TARGET=*.md .. note:: - + Wildcards can be used to run against all files matching a string, or an extension. The example above will match against all :code:`.md` files, and :code:`TARGET=doc*` will match both :code:`doc_1.md` and :code:`doc_2.md`. @@ -652,4 +678,5 @@ Other resources .. |notfound.extension| replace:: ``notfound.extension`` .. _notfound.extension: https://sphinx-notfound-page.readthedocs.io/en/latest/ -.. _woke documentation: https://docs.getwoke.tech/ignore \ No newline at end of file +.. _woke documentation: https://docs.getwoke.tech/ignore +.. _#197: https://github.com/canonical/sphinx-docs-starter-pack/issues/197