feat(docs): refine setup

- removes double `use flake` in root `.envrc`
- adds a `.envrc` for docs
- moves all docs related config inside the `docs` directory
- updates contribution guide explaining how to contribute docs
- updates docs github workflow to work with these changes

Signed-off-by: Brian McGee <[email protected]>

Author: brianmcgee

.envrc

@@ -3,5 +3,4 @@ dotenv_if_exists .env.local
 
 watch_file nix/devshell.nix
 
-use flake
-use flake .#docs
+use flake

.github/workflows/gh-pages.yml

@@ -33,12 +33,12 @@ jobs:
             - name: Deploy main
               if: ${{ github.ref_name == 'main' }}
               run: |
-                  nix develop .#docs --command bash -c "mike deploy -p main"
+                  nix develop .#docs --command bash -c "cd docs && mike deploy -p main"
             - name: Deploy version
               if: startsWith(github.ref, 'refs/tags/v')
               run: |
                   REF_NAME=${{ github.ref_name }}
                   MAJOR_MINOR=${REF_NAME%.*}
                   # strip the leading v from the ref_name
                   # update the latest alias          
-                  nix develop .#docs --command bash -c "mike deploy -p -u ${MAJOR_MINOR} latest"
+                  nix develop .#docs --command bash -c "cd docs && mike deploy -p -u ${MAJOR_MINOR} latest"

docs/.envrc

@@ -0,0 +1,3 @@
+source_up
+
+use flake .#docs

docs/content/contributing/docs.md

@@ -1,22 +1,25 @@
 # Documentation
 
-There is a separate [devshell] called `docs` which is provided for working with the docs locally.
+There is a `docs` package which can be built as follows:
 
-It can be entered by running: `nix develop .#docs`
+```console
+❯ nix build .#docs
+```
+
+This produces a static build of the docs and places it in a symlink called `result` in the same directory.
+
+We can re-use this package as a [devshell], relying upon it to provide the necessary dependencies for developing the
+docs.
 
 ```nix title="nix/devshells/docs.nix"
---8<-- "nix/devshells/docs.nix"
+--8<-- "nix/packages/docs.nix"
 ```
 
 The docs are based on [MkDocs] and the [MkDocs Material] theme.
-You will find its configuration and content in the following locations:
-
-- `mkdocs.yaml`
-- `./docs`
 
 ## Serve locally
 
-To serve the docs locally run `mkdocs serve` from the root of the repository:
+To serve the docs locally run `mkdocs serve` from the `docs` directory:
 
 ```console
 ❯ mkdocs serve

mkdocs.yml docs/mkdocs.yml

@@ -20,11 +20,11 @@ validation:
 
 # Configuration
 
-docs_dir: docs/content
+docs_dir: content
 
 theme:
     name: material
-    custom_dir: docs/theme
+    custom_dir: theme
 
     logo: assets/images/logo.png
     favicon: assets/images/logo.png
@@ -102,7 +102,8 @@ markdown_extensions:
           linenums: true
           anchor_linenums: true
     - pymdownx.inlinehilite
-    - pymdownx.snippets
+    - pymdownx.snippets:
+          base_path: ../.
     - pymdownx.keys
 
 plugins:

nix/packages/docs.nix

@@ -1,17 +1,13 @@
-{
-  pkgs,
-  perSystem,
-  ...
-}:
+{pkgs, perSystem, ...}:
 pkgs.stdenvNoCC.mkDerivation {
   name = "docs";
 
   unpackPhase = ''
-    cp ${../../mkdocs.yml} mkdocs.yaml
-    cp -r ${../../docs} docs
+    cp -r ${../../docs}/* .
+    ls -alr
   '';
 
-  nativeBuildInputs = with pkgs;
+  nativeBuildInputs =
     (with pkgs.python3Packages; [
       mike
       mkdocs