feat: adding mkdocs into guides and cookiecutter template (#662)

* Initial mkdocs additions

* Updating mkdocs documentation

* Updating mkdocs

* Updating copier

* I am dumb

* Newline

* Ensuring copier and cookiecutter work

* style: pre-commit fixes

* WIP: some additions

Signed-off-by: Henry Schreiner <[email protected]>

* fix: can't make a directory conditional

Signed-off-by: Henry Schreiner <[email protected]>

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* style: pre-commit fixes

* fix: minor fixup from looking at the diff

Signed-off-by: Henry Schreiner <[email protected]>

* fix: some styling corrections

Signed-off-by: Henry Schreiner <[email protected]>

* ci: update for new option

Signed-off-by: Henry Schreiner <[email protected]>

* chore: more style adjustments

Signed-off-by: Henry Schreiner <[email protected]>

* Apply suggestions from code review

Co-authored-by: Copilot <[email protected]>

* chore: colour -> color

Signed-off-by: Henry Schreiner <[email protected]>

* chore: a few more updates inspired by copilot

Signed-off-by: Henry Schreiner <[email protected]>

* chore: fix one more space

Signed-off-by: Henry Schreiner <[email protected]>

* fix: serve or build mkdocs

Signed-off-by: Henry Schreiner <[email protected]>

---------

Signed-off-by: Henry Schreiner <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Henry Schreiner <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 4 people

.github/workflows/reusable-cookie.yml

@@ -46,47 +46,49 @@ jobs:
         run: uv tool install nox
 
       - name: Test pybind11
-        run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs)'
+        run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs, sphinx)'
 
       - name: Test scikit-build
-        run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs)'
+        run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, sphinx)'
 
       - name: Test poetry
-        run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs)'
+        run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs, sphinx)'
 
       - name: Test flit
-        run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs)'
+        run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs, mkdocs)'
 
       - name: Test uv
-        run: nox -s 'tests(uv, novcs)'
+        run: nox -s 'tests(uv, novcs, sphinx)'
 
       - name: Test pdm
-        run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs)'
+        run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs, sphinx)'
 
       - name: Test maturin
-        run: nox -s 'tests(maturin, novcs)'
+        run: nox -s 'tests(maturin, novcs, sphinx)'
 
       - name: Test hatch
-        run: nox -s 'tests(hatch, novcs)' -s 'tests(hatch, vcs)'
+        run: nox -s 'tests(hatch, novcs, sphinx)' -s 'tests(hatch, vcs, sphinx)'
 
       - name: Test setuptools PEP 621
-        run: nox -s 'tests(setuptools, novcs)' -s 'tests(setuptools, vcs)'
+        run:
+          nox -s 'tests(setuptools, novcs, sphinx)' -s 'tests(setuptools, vcs,
+          sphinx)'
 
       - name: Native poetry tooling
         if: matrix.python-version != 'pypy-3.11'
         run: |
-          nox -s 'native(poetry, novcs)'
-          nox -s 'native(poetry, vcs)'
+          nox -s 'native(poetry, novcs, sphinx)'
+          nox -s 'native(poetry, vcs, sphinx)'
 
       - name: Native pdm tooling
-        run: nox -s 'native(pdm, novcs)' -s 'native(pdm, vcs)'
+        run: nox -s 'native(pdm, novcs, sphinx)' -s 'native(pdm, vcs, sphinx)'
 
       - name: Activate MSVC for Meson
         if: runner.os == 'Windows'
         uses: ilammy/msvc-dev-cmd@v1
 
       - name: Test meson-python
-        run: nox -s 'tests(mesonpy, novcs)'
+        run: nox -s 'tests(mesonpy, novcs, sphinx)'
 
       - name: Compare copier template generation
         run: nox -s compare_copier
@@ -114,52 +116,52 @@ jobs:
 
       - name: Test pybind11
         run: |
-          nox -s 'nox(pybind11, vcs)'
-          nox -s 'nox(pybind11, vcs)' -- docs
+          nox -s 'nox(pybind11, vcs, sphinx)'
+          nox -s 'nox(pybind11, vcs, sphinx)' -- docs
 
       - name: Test scikit-build
         run: |
-          nox -s 'nox(skbuild, vcs)'
-          nox -s 'nox(skbuild, vcs)' -- docs
+          nox -s 'nox(skbuild, vcs, sphinx)'
+          nox -s 'nox(skbuild, vcs, mkdocs)' -- docs
 
       - name: Test poetry
         run: |
-          nox -s 'nox(poetry, novcs)'
-          nox -s 'nox(poetry, novcs)' -- docs
+          nox -s 'nox(poetry, novcs, sphinx)'
+          nox -s 'nox(poetry, novcs, mkdocs)' -- docs
 
       - name: Test flit
         run: |
-          nox -s 'nox(flit, novcs)'
-          nox -s 'nox(flit, novcs)' -- docs
+          nox -s 'nox(flit, novcs, mkdocs)'
+          nox -s 'nox(flit, novcs, mkdocs)' -- docs
 
       - name: Test pdm
         run: |
-          nox -s 'nox(pdm, vcs)'
-          nox -s 'nox(pdm, vcs)' -- docs
+          nox -s 'nox(pdm, vcs, sphinx)'
+          nox -s 'nox(pdm, vcs, sphinx)' -- docs
 
       - name: Test maturin
         run: |
-          nox -s 'nox(maturin, novcs)'
-          nox -s 'nox(maturin, novcs)' -- docs
+          nox -s 'nox(maturin, novcs, sphinx)'
+          nox -s 'nox(maturin, novcs, sphinx)' -- docs
 
       - name: Test hatch
         run: |
-          nox -s 'nox(hatch, vcs)'
-          nox -s 'nox(hatch, vcs)' -- docs
+          nox -s 'nox(hatch, vcs, mkdocs)'
+          nox -s 'nox(hatch, vcs, mkdocs)' -- docs
 
       - name: Test setuptools PEP 621
         run: |
-          nox -s 'nox(setuptools, vcs)'
-          nox -s 'nox(setuptools, vcs)' -- docs
+          nox -s 'nox(setuptools, vcs, sphinx)'
+          nox -s 'nox(setuptools, vcs, sphinx)' -- docs
 
       - name: Activate MSVC for Meson
         if: runner.os == 'Windows'
         uses: ilammy/msvc-dev-cmd@v1
 
       - name: Test meson-python
         run: |
-          nox -s 'nox(mesonpy, novcs)'
-          nox -s 'nox(mesonpy, novcs)' -- docs
+          nox -s 'nox(mesonpy, novcs, sphinx)'
+          nox -s 'nox(mesonpy, novcs, sphinx)' -- docs
 
   dist:
     name: Distribution build

cookiecutter.json

@@ -18,6 +18,7 @@
     "mesonpy",
     "maturin"
   ],
+  "docs": ["sphinx", "mkdocs"],
   "vcs": true,
   "__year": "{% now 'utc', '%Y' %}",
   "__project_slug": "{{ cookiecutter.project_name | lower | replace('-', '_') | replace('.', '_') }}",
@@ -45,6 +46,11 @@
       "mesonpy": "Meson-python                   - Compiled C++ (also good)",
       "maturin": "Maturin                       - Compiled Rust (recommended)"
     },
+    "docs": {
+      "__prompt__": "Choose your documentation tool",
+      "sphinx": "Sphinx",
+      "mkdocs": "MkDocs"
+    },
     "vcs": "Use version control for versioning"
   }
 }

copier.yml

@@ -82,6 +82,14 @@ backend:
     "Maturin                        - Compiled Rust (recommended)": maturin
   # [[[end]]]
 
+# [[[cog print(cc.docs.yaml()) ]]]
+docs:
+  help: Choose your documentation tool
+  choices:
+    "Sphinx": sphinx
+    "MkDocs": mkdocs
+  # [[[end]]]
+
 # [[[cog print(cc.vcs.yaml()) ]]]
 vcs:
   type: bool

docs/README.md

@@ -11,7 +11,7 @@ scientists and research software engineers. The repository contains:
 ## Contributing to the documentation
 
 To build locally, install rbenv (remember to run `rbenv init` after installing,
-and `rbenv install 3.1.2`). Then:
+and `rbenv install 3.4.1`). Then:
 
 ```bash
 bundle install