Add docs-build session (#498)

* Add docs-build session

* Install sphinx

* Code review

* clean_build_path return type

* Rerun checks

* Test session fix

* Fix update documentation

* Code review 2

* Update test workflow and sessions docs

* Documentation review

* CI: Do not run docs session in generated project

Co-authored-by: Claudio Jolowicz <[email protected]>

Author: Thiago C. D'Ávila

.github/workflows/tests.yml

@@ -73,9 +73,6 @@ jobs:
       - name: Run test suite using Nox
         run: nox --force-color
         working-directory: hypermodern-python
-      - name: Build project documentation
-        run: nox --force-color --session=docs
-        working-directory: hypermodern-python
       - name: Install dependencies using Poetry
         run: poetry install --ansi
         working-directory: hypermodern-python

docs/guide.rst

@@ -1048,18 +1048,19 @@ The following table gives an overview of the available Nox sessions:
    :class: hypermodern-table
    :widths: auto
 
-   ========================================== ================================= ================== =========
-   Session                                    Description                       Python              Default
-   ========================================== ================================= ================== =========
-   :ref:`coverage <The coverage session>`     Report coverage with Coverage.py_ ``3.8``
-   :ref:`docs <The docs session>`             Build Sphinx_ documentation       ``3.8``
-   :ref:`mypy <The mypy session>`             Type-check with mypy_             ``3.6`` … ``3.8``      ✓
-   :ref:`pre-commit <The pre-commit session>` Lint with pre-commit_             ``3.8``                ✓
-   :ref:`safety <The safety session>`         Scan dependencies with Safety_    ``3.8``                ✓
-   :ref:`tests <The tests session>`           Run tests with pytest_            ``3.6`` … ``3.8``      ✓
-   :ref:`typeguard <The typeguard session>`   Type-check with Typeguard_        ``3.6`` … ``3.8``      ✓
-   :ref:`xdoctest <The xdoctest session>`     Run examples with xdoctest_       ``3.6`` … ``3.8``
-   ========================================== ================================= ================== =========
+   ========================================== ===================================== ================== =========
+   Session                                    Description                           Python              Default
+   ========================================== ===================================== ================== =========
+   :ref:`coverage <The coverage session>`     Report coverage with Coverage.py_     ``3.8``
+   :ref:`docs <The docs session>`             Build and serve Sphinx_ documentation ``3.8``
+   :ref:`docs-build <The docs-build session>` Build Sphinx_ documentation           ``3.8``                ✓
+   :ref:`mypy <The mypy session>`             Type-check with mypy_                 ``3.6`` … ``3.8``      ✓
+   :ref:`pre-commit <The pre-commit session>` Lint with pre-commit_                 ``3.8``                ✓
+   :ref:`safety <The safety session>`         Scan dependencies with Safety_        ``3.8``                ✓
+   :ref:`tests <The tests session>`           Run tests with pytest_                ``3.6`` … ``3.8``      ✓
+   :ref:`typeguard <The typeguard session>`   Type-check with Typeguard_            ``3.6`` … ``3.8``      ✓
+   :ref:`xdoctest <The xdoctest session>`     Run examples with xdoctest_           ``3.6`` … ``3.8``
+   ========================================== ===================================== ================== =========
 
 
 .. _The docs session:
@@ -1073,23 +1074,16 @@ Build the documentation using the Nox session ``docs``:
 
    $ nox --session=docs
 
-The docs session runs the command ``sphinx-build``
-to generate the HTML documentation from the Sphinx directory.
-
-In `interactive mode`__---such
-as when invoking Nox from a terminal---sphinx-autobuild_ is used instead.
-This tool has several advantages
-when you are editing the documentation files:
-
-__ https://nox.thea.codes/en/stable/usage.html#forcing-non-interactive-behavior
+The docs session runs the command ``sphinx-autobuild`` to generate the HTML documentation from the Sphinx directory.
+This tool has several advantages over ``sphinx-build`` when you are editing the documentation files:
 
 - It rebuilds the documentation whenever a change is detected.
 - It spins up a web server with live reloading.
 - It opens the location of the web server in your browser.
 
 .. _sphinx-autobuild: https://github.com/GaretJax/sphinx-autobuild
 
-Use the ``--`` separator to pass additional options to either tool.
+Use the ``--`` separator to pass additional options.
 For example, to treat warnings as errors and run in nit-picky mode:
 
 .. code:: console
@@ -1099,6 +1093,19 @@ For example, to treat warnings as errors and run in nit-picky mode:
 This Nox session always runs with the current major release of Python.
 
 
+.. _The docs-build session:
+
+The docs-build session
+----------------------
+
+The ``docs-build`` session runs the command ``sphinx-build`` to generate the HTML documentation from the Sphinx directory.
+
+This session is meant to be run as a part of automated checks.
+Use the interactive ``docs`` session instead while you're editing the documentation.
+
+This Nox session always runs with the current major release of Python.
+
+
 .. _The mypy session:
 
 The mypy session
@@ -2275,7 +2282,7 @@ __ https://help.github.com/en/actions/automating-your-workflow-with-github-actio
    :ref:`tests <The tests session>`           Ubuntu                 3.8, 3.7, 3.6
    :ref:`tests <The tests session>`           Windows                3.8
    :ref:`tests <The tests session>`           macOS                  3.8
-   :ref:`docs <The docs session>`             Ubuntu                 3.8
+   :ref:`docs-build <The docs-build session>` Ubuntu                 3.8
    ========================================== ====================== ===============
 
 The workflow uploads the generated documentation as a `workflow artifact`__.

{{cookiecutter.project_name}}/.github/workflows/tests.yml

@@ -23,7 +23,7 @@ jobs:
           - { python-version: 3.8, os: windows-latest, session: "tests" }
           - { python-version: 3.8, os: macos-latest, session: "tests" }
           - { python-version: 3.8, os: ubuntu-latest, session: "typeguard" }
-          - { python-version: 3.8, os: ubuntu-latest, session: "docs" }
+          - { python-version: 3.8, os: ubuntu-latest, session: "docs-build" }
 
     env:
       NOXSESSION: {{ "${{ matrix.session }}" }}
@@ -81,7 +81,7 @@ jobs:
           nox --force-color --python=${{ "{{" }} matrix.python-version {{ "}}" }}
 
       - name: Upload documentation
-        if: matrix.session == 'docs'
+        if: matrix.session == 'docs-build'
         uses: actions/upload-artifact@v2
         with:
           name: docs

{{cookiecutter.project_name}}/noxfile.py

@@ -11,7 +11,14 @@
 
 package = "{{cookiecutter.package_name}}"
 python_versions = ["3.8", "3.7", "3.6"]
-nox.options.sessions = "pre-commit", "safety", "mypy", "tests", "typeguard"
+nox.options.sessions = (
+    "pre-commit",
+    "safety",
+    "mypy",
+    "tests",
+    "typeguard",
+    "docs-build",
+)
 
 
 class Poetry:
@@ -254,22 +261,29 @@ def xdoctest(session: Session) -> None:
     session.run("python", "-m", "xdoctest", package, *args)
 
 
-@nox.session(python="3.8")
-def docs(session: Session) -> None:
+@nox.session(name="docs-build", python="3.8")
+def docs_build(session: Session) -> None:
     """Build the documentation."""
     args = session.posargs or ["docs", "docs/_build"]
+    install_package(session)
+    install(session, "sphinx")
+
+    build_dir = Path("docs", "_build")
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
 
-    if session.interactive and not session.posargs:
-        args.insert(0, "--open-browser")
+    session.run("sphinx-build", *args)
 
-    builddir = Path("docs", "_build")
-    if builddir.exists():
-        shutil.rmtree(builddir)
 
+@nox.session(python="3.8")
+def docs(session: Session) -> None:
+    """Build and serve the documentation with live reloading on file changes."""
+    args = session.posargs or ["--open-browser", "docs", "docs/_build"]
     install_package(session)
     install(session, "sphinx", "sphinx-autobuild")
 
-    if session.interactive:
-        session.run("sphinx-autobuild", *args)
-    else:
-        session.run("sphinx-build", *args)
+    build_dir = Path("docs", "_build")
+    if build_dir.exists():
+        shutil.rmtree(build_dir)
+
+    session.run("sphinx-autobuild", *args)