Add nox builds for our docs (#724)

README.md

@@ -6,10 +6,40 @@ See [the Pilot Hubs documentation](https://pilot-hubs.2i2c.org) for more informa
 
 ## Building the documentation
 
-To build this documentation follow these steps:
+The documentation is built with [the Sphinx documentation engine](https://sphinx-doc.org).
+
+### Automatically with `nox`
+
+The easiest way to build the documentation in this repository is to use [the `nox` automation tool](https://nox.thea.codes/), a tool for quickly building environments and running commands within them.
+This ensures that your environment has all the dependencies needed to build the documentation.
+
+To do so, follow these steps:
+
+1. Install `nox`
+
+   ```console
+   $ pip install nox
+   ```
+2. Build the documentation:
+
+   ```console
+   $ nox -s docs
+   ```
+
+This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `docs/_build/html`.
+
+To build live documentation that updates when you update local files, run the following command:
+
+```console
+$ nox -s docs-live
+```
+
+### Manually with `conda`
+
+If you wish to manually build the documentation, you can use `conda` to do so.
 
 1. Create a `conda` environment to build the documentation.
-   
+
    ```bash
    conda env create -f docs/environment.yml -n pilot-hubs-docs
    ```
@@ -21,7 +51,7 @@ To build this documentation follow these steps:
    ```
 
 3. Build the documentation:
-   
+
    ```
    make html
    ```

docs/environment.yml

@@ -3,13 +3,6 @@ channels:
 - conda-forge
 dependencies:
 - go-terraform-docs
-- pip
 - python=3.8
 - pip:
-  - myst-parser[sphinx,linkify]
-  - pandas
-  - pyyaml
-  - requests
-  - sphinx-autobuild
-  - git+https://github.com/2i2c-org/sphinx-2i2c-theme
-  - sphinx-panels
+  - -r requirements.txt

docs/requirements.txt

@@ -0,0 +1,7 @@
+myst-parser[sphinx,linkify]
+pandas
+pyyaml
+requests
+sphinx-autobuild
+sphinx-panels
+git+https://github.com/2i2c-org/sphinx-2i2c-theme

noxfile.py

@@ -0,0 +1,25 @@
+import nox
+
+nox.options.reuse_existing_virtualenvs = True
+
+BUILD_COMMAND = ["-b", "html", "docs", "docs/_build/html"]
+
+def install_deps(session):
+    # Manually installing this because conda is a bit wonky w/ nox
+    session.conda_install("--channel=conda-forge", "go-terraform-docs", "python=3.8")
+    session.install("-r", "docs/requirements.txt")
+
+@nox.session(venv_backend='conda')
+def docs(session):
+    install_deps(session)
+    session.run("sphinx-build", *BUILD_COMMAND)
+
+@nox.session(name="docs-live", venv_backend='conda')
+def docs_live(session):
+    install_deps(session)
+
+    cmd = ["sphinx-autobuild"]
+    for path in ["*/_build/*", "*/tmp/*", "*/reference/terraform.md"]:
+        cmd.extend(['--ignore', path])
+    cmd.extend(BUILD_COMMAND)
+    session.run(*cmd)