Merge pull request #102 from staticdev/nox-docs

Nox refactor

Author: Thiago C. D'Ávila

.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

noxfile.py

@@ -1,12 +1,9 @@
 """Nox sessions."""
-import contextlib
+import hashlib
 import shutil
 import sys
-import tempfile
 from pathlib import Path
 from textwrap import dedent
-from typing import cast
-from typing import Iterator
 
 import nox
 from nox.sessions import Session
@@ -15,7 +12,14 @@
 package = "git_portfolio"
 # python_versions = ["3.9", "3.8", "3.7"]
 python_versions = ["3.8", "3.7"]
-nox.options.sessions = "pre-commit", "safety", "mypy", "tests", "typeguard"
+nox.options.sessions = (
+    "pre-commit",
+    "safety",
+    "mypy",
+    "tests",
+    "typeguard",
+    "docs-build",
+)
 
 
 class Poetry:
@@ -29,46 +33,62 @@ def __init__(self, session: Session) -> None:
         """Constructor."""
         self.session = session
 
-    @contextlib.contextmanager
-    def export(self, *args: str) -> Iterator[Path]:
+    def export(self, path: Path, *, dev: bool) -> None:
         """Export the lock file to requirements format.
 
         Args:
-            args: Command-line arguments for ``poetry export``.
-
-        Yields:
-            The path to the requirements file.
-        """
-        with tempfile.TemporaryDirectory() as directory:
-            requirements = Path(directory) / "requirements.txt"
-            self.session.run(
-                "poetry",
-                "export",
-                *args,
-                "--format=requirements.txt",
-                f"--output={requirements}",
-                external=True,
-            )
-            yield requirements
-
-    def version(self) -> str:
-        """Retrieve the package version.
-
-        Returns:
-            The package version.
+            path: The destination path.
+            dev: If True, include development dependencies.
         """
-        output = self.session.run(
-            "poetry", "version", external=True, silent=True, stderr=None
+        options = ["--dev"] if dev else []
+        self.session.run(
+            "poetry",
+            "export",
+            "--format=requirements.txt",
+            f"--output={path}",
+            *options,
+            external=True,
         )
-        return cast(str, output).split()[1]
 
-    def build(self, *args: str) -> None:
+    def build(self, *args: str) -> str:
         """Build the package.
 
         Args:
             args: Command-line arguments for ``poetry build``.
+
+        Returns:
+            The basename of the wheel built by Poetry.
         """
-        self.session.run("poetry", "build", *args, external=True)
+        output = self.session.run(
+            "poetry", "build", *args, external=True, silent=True, stderr=None
+        )
+        assert isinstance(output, str)  # noqa: S101
+        return output.split()[-1]
+
+
+def export_requirements(session: Session, *, dev: bool) -> Path:
+    """Export the lock file to requirements format.
+
+    Args:
+        session: The Session object.
+        dev: If True, include development dependencies.
+
+    Returns:
+        The path to the requirements file.
+    """
+    tmpdir = Path(session.create_tmp())
+    name = "dev-requirements.txt" if dev else "requirements.txt"
+    path = tmpdir / name
+    hashfile = tmpdir / f"{name}.hash"
+
+    lockdata = Path("poetry.lock").read_bytes()
+    digest = hashlib.blake2b(lockdata).hexdigest()
+
+    if not hashfile.is_file() or hashfile.read_text() != digest:
+        Poetry(session).export(path, dev=dev)
+        hashfile.write_text(digest)
+
+    return path
 
 
 def install_package(session: Session) -> None:
@@ -84,16 +104,11 @@ def install_package(session: Session) -> None:
         session: The Session object.
     """
     poetry = Poetry(session)
+    wheel = poetry.build("--format=wheel")
+    requirements = export_requirements(session, dev=False)
 
-    with poetry.export() as requirements:
-        session.install(f"--requirement={requirements}")
-
-    poetry.build("--format=wheel")
-
-    version = poetry.version()
-    session.install(
-        "--no-deps", "--force-reinstall", f"dist/{package}-{version}-py3-none-any.whl"
-    )
+    session.install(f"--requirement={requirements}")
+    session.install("--no-deps", "--force-reinstall", f"dist/{wheel}")
 
 
 def install(session: Session, *args: str) -> None:
@@ -107,9 +122,8 @@ def install(session: Session, *args: str) -> None:
         session: The Session object.
         args: Command-line arguments for ``pip install``.
     """
-    poetry = Poetry(session)
-    with poetry.export("--dev") as requirements:
-        session.install(f"--constraint={requirements}", *args)
+    requirements = export_requirements(session, dev=True)
+    session.install(f"--constraint={requirements}", *args)
 
 
 def activate_virtualenv_in_precommit_hooks(session: Session) -> None:
@@ -189,10 +203,9 @@ def precommit(session: Session) -> None:
 @nox.session(python="3.8")
 def safety(session: Session) -> None:
     """Scan dependencies for insecure packages."""
-    poetry = Poetry(session)
-    with poetry.export("--dev", "--without-hashes") as requirements:
-        install(session, "safety")
-        session.run("safety", "check", f"--file={requirements}", "--bare")
+    install(session, "safety")
+    requirements = export_requirements(session, dev=True)
+    session.run("safety", "check", f"--file={requirements}", "--bare")
 
 
 @nox.session(python=python_versions)
@@ -210,7 +223,7 @@ def mypy(session: Session) -> None:
 def tests(session: Session) -> None:
     """Run the test suite."""
     install_package(session)
-    install(session, "coverage[toml]", "pytest", "pytest_mock")
+    install(session, "coverage[toml]", "pygments", "pytest", "pytest_mock")
     try:
         session.run("coverage", "run", "--parallel", "-m", "pytest", *session.posargs)
     finally:
@@ -236,7 +249,7 @@ def coverage(session: Session) -> None:
 def typeguard(session: Session) -> None:
     """Runtime type checking using Typeguard."""
     install_package(session)
-    install(session, "pytest", "typeguard", "pytest_mock")
+    install(session, "pygments", "pytest", "pytest_mock", "typeguard")
     session.run("pytest", f"--typeguard-packages={package}", *session.posargs)
 
 
@@ -249,22 +262,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)