Refactor documenation nox tasks (#273)

Author: Nicoretti

.github/workflows/checks.yml

@@ -38,7 +38,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run python -m nox -s build-docs
+          poetry run python -m nox -s docs:build
 
   Lint:
     name: Linting (Python-${{ matrix.python-version }})

.github/workflows/gh-pages.yml

@@ -18,7 +18,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run sphinx-multiversion doc/ .html-documentation 
+          poetry run python -m nox -s docs:multiversion
 
       - name: Deploy
         uses: JamesIves/github-pages-deploy-action@v4.6.3

doc/changes/unreleased.md

@@ -3,10 +3,15 @@
 ## 🚨 Breaking Changes
 
 * Dropped python 3.8 support
+* Changed names of Documentation related nox tasks
+    - `build-docs` -> `docs:build`
+    - `open-docs` -> `docs:open`
+    - `clean-docs` -> `docs:clean`
 
 ## ✨ Added
 
 * Added support for multi version Documentation
+* Added nox tasks for building multi-version documentation
 
 ## 🐞 Fixed
 

doc/user_guide/getting_started.rst

@@ -71,7 +71,7 @@ Build and open the documentation:
 
 .. code-block:: shell
 
-    nox -s build-docs  open-docs
+    nox -s docs:build  docs:open
 
 Execute the unit tests of the project:
 
@@ -191,9 +191,9 @@ You are ready to use the toolbox. With *nox -l* you can list all available tasks
     - unit-tests -> Runs all unit tests
     - integration-tests -> Runs the all integration tests
     - coverage -> Runs all tests (unit + integration) and reports the code coverage
-    - build-docs -> Builds the project documentation
-    - open-docs -> Opens the built project documentation
-    - clean-docs -> Removes the documentations build folder
+    - docs:build -> Builds the project documentation
+    - docs:open -> Opens the built project documentation
+    - docs:clean -> Removes the documentations build folder
     - report -> Collects and generates a metrics summary for the workspace
 
     sessions marked with * are selected, sessions marked with - are skipped.

exasol/toolbox/nox/_documentation.py

@@ -26,13 +26,29 @@ def _build_docs(session: nox.Session, config: Config) -> None:
     )
 
 
-@nox.session(name="build-docs", python=False)
+def _build_multiversion_docs(session: nox.Session, config: Config) -> None:
+    session.run(
+        "poetry",
+        "run",
+        "sphinx-multiversion",
+        f"{config.doc}",
+        DOCS_OUTPUT_DIR,
+    )
+
+
+@nox.session(name="docs:multiversion", python=False)
+def build_multiversion(session: Session) -> None:
+    """Builds the project documentation"""
+    _build_multiversion_docs(session, PROJECT_CONFIG)
+
+
+@nox.session(name="docs:build", python=False)
 def build_docs(session: Session) -> None:
     """Builds the project documentation"""
     _build_docs(session, PROJECT_CONFIG)
 
 
-@nox.session(name="open-docs", python=False)
+@nox.session(name="docs:open", python=False)
 def open_docs(session: Session) -> None:
     """Opens the built project documentation"""
     docs_folder = PROJECT_CONFIG.root / DOCS_OUTPUT_DIR
@@ -42,7 +58,7 @@ def open_docs(session: Session) -> None:
     webbrowser.open_new_tab(index.as_uri())
 
 
-@nox.session(name="clean-docs", python=False)
+@nox.session(name="docs:clean", python=False)
 def clean_docs(_session: Session) -> None:
     """Removes the documentations build folder"""
     docs_folder = PROJECT_CONFIG.root / DOCS_OUTPUT_DIR

exasol/toolbox/templates/github/workflows/checks.yml

@@ -44,7 +44,7 @@ jobs:
 
       - name: Build Documentation
         run: |
-          poetry run python -m nox -s build-docs
+          poetry run python -m nox -s docs:build
 
   Lint:
     name: Linting (Python-${{ matrix.python-version }})