doc: provide a unified requirements file

To ease maintenance and keeping track of which docset requires what. Signed-off-by: Gerard Marull-Paretas <gerard.marull@nordicsemi.no>
nrfconnect · Aug 11, 2023 · b612c1d · b612c1d
1 parent 1ceb598
commit b612c1d
Show file tree

Hide file tree

Showing 4 changed files with 53 additions and 27 deletions.
diff --git a/.github/workflows/docbuild.yml b/.github/workflows/docbuild.yml
@@ -48,11 +48,11 @@ jobs:
           tar xf doxygen-${DOXYGEN_VERSION}.linux.bin.tar.gz
           echo "${PWD}/doxygen-${DOXYGEN_VERSION}/bin" >> $GITHUB_PATH
 
-      - name: Install base dependencies
+      - name: Install Python dependencies
         working-directory: ncs
         run: |
           sudo pip3 install -U setuptools wheel pip
-          pip3 install -r nrf/scripts/requirements-base.txt
+          pip3 install -r nrf/doc/requirements.txt
 
       - name: West init and update
         working-directory: ncs
@@ -61,11 +61,6 @@ jobs:
           west update
           west zephyr-export
 
-      - name: Install documentation dependencies
-        working-directory: ncs
-        run: |
-          pip3 install -r zephyr/doc/requirements.txt -r nrf/doc/requirements.txt
-
       - name: Build documentation
         working-directory: ncs/nrf
         run: |

diff --git a/doc/nrf/conf.py b/doc/nrf/conf.py
@@ -202,9 +202,7 @@
 ]
 ncs_tool_versions_python_deps = [
     ZEPHYR_BASE / "scripts" / "requirements-base.txt",
-    ZEPHYR_BASE / "doc" / "requirements.txt",
     MCUBOOT_BASE / "scripts" / "requirements.txt",
-    NRF_BASE / "scripts" / "requirements-base.txt",
     NRF_BASE / "doc" / "requirements.txt",
     NRF_BASE / "scripts" / "requirements-build.txt",
 ]

diff --git a/doc/nrf/installation/recommended_versions.rst b/doc/nrf/installation/recommended_versions.rst
@@ -235,22 +235,43 @@ Building and running applications, samples, and tests
 Building documentation
 ----------------------
 
+Python documentation dependencies are listed in the following table. They can
+all be installed using the ``doc/requirements.txt`` file using ``pip``.
+
 .. list-table::
    :header-rows: 1
 
    * - Package
      - Version
-   * - recommonmark
-     - :ncs-tool-version:`RECOMMONMARK_VERSION`
-   * - sphinxcontrib-mscgen
-     - :ncs-tool-version:`SPHINXCONTRIB_MSCGEN_VERSION`
+   * - azure-storage-blob
+     - :ncs-tool-version:`AZURE_STORAGE_BLOB_VERSION`
    * - breathe
      - :ncs-tool-version:`BREATHE_VERSION`
+   * - m2r2
+     - :ncs-tool-version:`M2R2_VERSION`
+   * - PyYAML
+     - :ncs-tool-version:`PYYAML_VERSION`
+   * - pykwalify
+     - :ncs-tool-version:`PYKWALIFY_VERSION`
+   * - recommonmark
+     - :ncs-tool-version:`RECOMMONMARK_VERSION`
    * - sphinx
      - :ncs-tool-version:`SPHINX_VERSION`
+   * - sphinx-copybutton
+     - :ncs-tool-version:`SPHINX_COPYBUTTON_VERSION`
    * - sphinx-ncs-theme
      - :ncs-tool-version:`SPHINX_NCS_THEME_VERSION`
+   * - sphinx-notfound-page
+     - :ncs-tool-version:`SPHINX_NOTFOUND_PAGE_VERSION`
    * - sphinx-tabs
      - :ncs-tool-version:`SPHINX_TABS_VERSION`
-   * - sphinxcontrib-svg2pdfconverter
-     - :ncs-tool-version:`SPHINXCONTRIB_SVG2PDFCONVERTER_VERSION`
+   * - sphinx-togglebutton
+     - :ncs-tool-version:`SPHINX_TOGGLEBUTTON_VERSION`
+   * - sphinx_markdown_tables
+     - :ncs-tool-version:`SPHINX_MARKDOWN_TABLES_VERSION`
+   * - sphinxcontrib-mscgen
+     - :ncs-tool-version:`SPHINXCONTRIB_MSCGEN_VERSION`
+   * - sphinxcontrib-plantuml
+     - :ncs-tool-version:`SPHINXCONTRIB_PLANTUML_VERSION`
+   * - west
+     - :ncs-tool-version:`WEST_VERSION`
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,12 +1,24 @@
-recommonmark==0.6.0
-CommonMark>=0.9.1
-sphinxcontrib-mscgen>=0.6
-sphinx-ncs-theme>=1.0.3,<1.1
-m2r2>=0.3.2
-sphinxcontrib-plantuml
-pyyaml
-azure-storage-blob
-sphinx_markdown_tables
-breathe>=4.34
-sphinx-togglebutton
-sphinx-notfound-page
+# This file lists all the dependencies required to build the documentation.
+# To update this file, follow these basic rules:
+#   - Keep it sorted alphabetically
+#   - Mark which docsets are using each dependency
+#   - Only specify version information if strictly required
+#   - Keep nrf/installation/recommended_versions.rst up to date
+
+# Extension                 | NCS | Kconfig | Matter | MCUboot | nrfx | nrfxlib | TF-M | Zephyr |
+azure-storage-blob        # |  X  |         |        |         |      |         |      |        |
+breathe                   # |  X  |         |        |         |      |    X    |      |   X    |
+m2r2                      # |     |         |        |         |  X   |         |      |        |
+PyYAML                    # |  X  |         |        |         |      |         |      |   X    |
+pykwalify                 # |     |         |        |         |      |         |      |   X    |
+recommonmark              # |     |         |   X    |    X    |      |         |      |        |
+sphinx~=6.2               # |  X  |    X    |   X    |    X    |   X  |    X    |  X   |   X    |
+sphinx-copybutton         # |  X  |         |        |         |      |         |      |   X    |
+sphinx-ncs-theme<1.1      # |  X  |         |        |         |      |         |      |        |
+sphinx-notfound-page      # |  X  |         |        |         |      |         |      |   X    |
+sphinx-tabs>=3.4          # |  X  |         |        |         |      |         |      |   X    |
+sphinx-togglebutton       # |  X  |         |        |         |      |         |      |        |
+sphinx_markdown_tables    # |     |         |   X    |         |      |         |      |        |
+sphinxcontrib-mscgen      # |  X  |         |        |         |      |    X    |      |        |
+sphinxcontrib-plantuml    # |     |         |        |         |      |         |  X   |        |
+west>=1.0.0               # |     |         |        |         |      |         |      |   X    |