Merge pull request #821 from rgaiacs/819-nox-script

Minor improvements to noxfile.py

Author: minrk

.gitignore

@@ -1,7 +1,6 @@
 __pycache__
 _build
-docs/_data/contributors/contributors-jupyterhub.txt
-docs/_data/outreachy/*.txt
+docs/_data/generated/*
 .ipynb_checkpoints
 .vscode
 .nox

docs/_data/contributors/gen_contributors.py

@@ -8,7 +8,9 @@
 
 # Load data that we'll use for the table
 path_data = Path(__file__).parent
+path_output = path_data.parent / "generated"
 path_contributor_data = path_data / "contributors-jupyterhub.yaml"
+path_output_contributor_data = path_output / "contributors-jupyterhub.txt"
 contributors = safe_load(path_contributor_data.read_text())
 keyvals = pd.read_csv(path_data / "contributor_key.csv", index_col=0)
 
@@ -109,4 +111,4 @@ def _short_contributor(contributor):
 snippet += ", ".join(map(_short_contributor, inactive_contributors))
 
 # Write a snippet that we will include in our docs
-path_contributor_data.with_suffix(".txt").write_text(snippet + "\n")
+path_output_contributor_data.write_text(snippet + "\n")

docs/_data/generated/.gitkeep

@@ -8,9 +8,10 @@
 
 # Set filepath to participants data file
 data_path = Path(__file__).resolve().parent
+generated_output = data_path.parent / "generated"
 participants_data_file = data_path.joinpath("outreachy_participants.json")
 participants_schema_file = data_path.joinpath("outreachy_participants.schema.json")
-output_path = data_path.joinpath("outreachy_participants.txt")
+output_path = generated_output.joinpath("outreachy_participants.txt")
 
 # Read in json defining Outreachy participants
 with open(participants_data_file) as f:

docs/_data/outreachy/outreachy_participants.py

@@ -1,19 +1,15 @@
 # Writing documentation
 
-All of the team's repositories are documented using [the Sphinx documentation engine](https://sphinx-doc.org).
-This page contains resources to help you understand Sphinx and the configurations we commonly use in our repositories.
+All of the team's repositories are documented using the [Sphinx] documentation engine.
+This page contains resources to help you understand [Sphinx] and the configurations we commonly use in our repositories.
+
+[Sphinx]: https://sphinx-doc.org
 
 ## MyST Markdown
 
-Many of our repositories use [MyST Markdown](https://myst-parser.readthedocs.io).
+Our repositories use [MyST Markdown](https://myst-parser.readthedocs.io).
 This is enabled via the [`myst-parser` Sphinx extension](https://myst-parser.readthedocs.io).
 
-## reStructuredText
-
-The default markup language used by Sphinx is [reStructuredText](https://www.sphinx-doc.org/en/master/usage/restructuredtext/).
-It is a rich and extensible way to write content for our documentation.
-See [the Sphinx reStructuredText documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/) for an in-depth guide of how to use it.
-
 ## Build documentation locally
 
 There are a few ways to build the documentation in our repositories.
@@ -22,41 +18,35 @@ Here are a few common ways to do so, from most- to least-automated.
 
 ### Building with `nox`
 
-We often use [the `nox` command line tool](https://nox.thea.codes/en/stable/) to build documentation locally.
+We use [the `nox` command line tool](https://nox.thea.codes/en/stable/) to automate the build documentation locally.
 `nox` is a tool for quickly running commands in an isolated build environment.
 It is similar to `Make`, but with a Python configuration and with local build environments that are isolated to each job that you run.
 
 `nox` is configured with [a file called `noxfile.py`](https://nox.thea.codes/en/stable/config.html).
 
-**To install `nox`**, run this command:
+**To install `nox`**, follow the [steps in Nox's documentation](https://nox.thea.codes/en/stable/tutorial.html#installation).
+
+**To see a list of available commands**, run
 
 ```bash
-pip install nox
+nox -l
 ```
 
-**To see a list of available commands**, run this command:
+**To install the requirements for documentation, build them locally, and have a live preview**, run
 
 ```bash
-nox -l
+nox -s docs -- live
 ```
 
-For example, we often name our documentation command `docs`.
-**To install the requirements for documentation and build them locally**, run:
+``````{note}
+If you don't want the live preview, run
 
-```
+```bash
 nox -s docs
 ```
 
 This will place the built HTML files in `docs/_build/html` for you to inspect as you wish.
-
-We often add an extra parameter to instead run a live server via [the `sphinx-autobuild` extension](https://github.com/executablebooks/sphinx-autobuild).
-**To build docs with a live serve that auto-reloads as you change things**, run this command:
-
-```
-nox -s docs -- live
-```
-
-Note that this will **only work for repositories that have a `noxfile.py` added**.
+``````
 
 (docs:build-make)=
 ### Building with `Makefile`s
@@ -66,18 +56,17 @@ Many of our repositories also have a `Makefile` that runs commands in your curre
 To do so, follow these steps:
 
 1. Install the requirements for the documentation. This is often in a `docs/requirements.txt` file.
-   Assuming a file in this location, run this command:
+   Assuming a file in this location, run
 
    ```bash
    pip install -r docs/requirements.txt
    ```
 2. Look for a `Makefile` in the `docs` repository.
-   This is auto-generated by Sphinx to help you build the documentation.
-   To build the `html` for our documentation, run this command:
+   This is auto-generated by [Sphinx] to help you build the documentation.
+   To build the `html` for our documentation, run
 
    ```bash
-   cd docs
-   make html
+   make -C docs html
    ```
 
    It will put the built documentation in `_build/html` (depending on our configuration this may change a bit).

docs/contribute/documentation.md

@@ -10,7 +10,7 @@ Here is the current JupyterHub team (listed alphabetically, with affiliation, an
 **Min Ragan-Kelley** acts as the team lead for the JupyterHub organization.
 
 ```{eval-rst}
-.. include:: ../_data/contributors/contributors-jupyterhub.txt
+.. include:: ../_data/generated/contributors-jupyterhub.txt
 ```
 
 (emoji-keys)=
@@ -33,5 +33,5 @@ internships with us. This includes the interns themselves who worked with us to
 improve JupyterHub, and the community members that donated their time and skills
 as mentors, coordinators and volunteers.
 
-```{include} ../_data/outreachy/outreachy_participants.txt
+```{include} ../_data/generated/outreachy_participants.txt
 ```

docs/team/index.md

@@ -1,26 +1,38 @@
-"""A nox configuration file so that we can build the documentation easily with nox.
-- see the README.md for information about nox.
-- ref: https://nox.thea.codes/en/stable/
-"""
+import os.path
+
 import nox
 
 nox.options.reuse_existing_virtualenvs = True
 
-build_command = ["-b", "dirhtml", "docs", "docs/_build/html"]
 
-@nox.session()
+@nox.session(default=False)
 def docs(session):
-    session.install("-r", "docs/requirements.txt")
+    """
+    Build the documentation and, optionally with '-- live', run a web server. 
+    """
+    docs_dir = "docs"
+    source_dir = os.path.join(docs_dir, "")  # where conf.py is located
+    data_dir = os.path.join(source_dir, "_data")
+    output_dir = os.path.join(docs_dir, "_build")
+
+    session.install("-r", os.path.join(docs_dir, "requirements.txt"))
+
+    doc_build_default_args = ["-b", "dirhtml", source_dir, output_dir]
+
     if "live" in session.posargs:
-        # Add relative paths to this if we ever need to ignore them
-        AUTOBUILD_IGNORE = [
-          "docs/_data",
-          "docs/_build",
-        ]
+        # For live preview, sphinx-autobuild is used.
+        # To avoid sphinx-autobuild be missing,
+        # sphinx-autobuild is installed explicitly.
+        session.install("sphinx-autobuild")
         cmd = ["sphinx-autobuild"]
-        for folder in AUTOBUILD_IGNORE:
+
+        # Add relative paths to this if we ever need to ignore them
+        autobuild_ignore = [output_dir, os.path.join(data_dir, "generated")]
+
+        for folder in autobuild_ignore:
             cmd.extend(["--ignore", f"*/{folder}/*"])
-        cmd.extend(build_command)
+
+        cmd.extend(doc_build_default_args)
         session.run(*cmd)
     else:
-        session.run("sphinx-build", *build_command)
+        session.run("sphinx-build", *doc_build_default_args)