feat: Change docs backend to mkdocs

alexandrainst · Nov 20, 2024 · bb7f9b6 · bb7f9b6
1 parent de8aef0
commit bb7f9b6
Show file tree

Hide file tree

Showing 9 changed files with 30 additions and 85 deletions.
diff --git a/cookiecutter.json b/cookiecutter.json
@@ -9,7 +9,9 @@
     "_pytest_version": "8.3.3",
     "_pytest_cov_version": "5.0.0",
     "_pre_commit_version": "3.8.0",
-    "_pdoc_version": "14.7.0",
+    "_mkdocs_material_version": "9.5.45",
+    "_mkdocs_plugin_include_markdown_version": "7.0.1",
+    "_mkdocs_plugin_include_dir_to_nav_version": "1.2.0",
     "_readme_coverage_badger_version": "0.1.2",
     "_click_version": "8.1.7",
     "_ruff_version": "0.7.1",

diff --git a/...oject_name}}/.github/workflows/{{'docs.yaml' if cookiecutter.open_source == 'y' else ''}} b/...oject_name}}/.github/workflows/{{'docs.yaml' if cookiecutter.open_source == 'y' else ''}}
diff --git a/{{cookiecutter.project_name}}/.gitignore b/{{cookiecutter.project_name}}/.gitignore
@@ -51,9 +51,6 @@ coverage.xml
 # Django stuff:
 *.log
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 target/
 
@@ -93,12 +90,6 @@ target/
 outputs/
 multirun/
 
-# Documentation
-docs/{{cookiecutter.project_name}}/
-docs/{{cookiecutter.project_name}}.html
-docs/index.html
-docs/search.js
-
 # Data
 data/raw/*
 !data/raw/.gitkeep
@@ -119,3 +110,6 @@ models/*
 
 # Python cache
 **/__pycache__/
+
+# Mkdocs compiled documentation
+site/
diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md
@@ -14,7 +14,7 @@
 ______________________________________________________________________
 [![Code Coverage](https://img.shields.io/badge/Coverage-0%25-red.svg)](https://github.com/alexandrainst/{{cookiecutter.project_name}}/tree/main/tests)
 {% if cookiecutter.open_source == 'y' -%}
-[![Documentation](https://img.shields.io/badge/docs-passing-green)](https://alexandrainst.github.io/{{cookiecutter.project_name}}/{{cookiecutter.project_name}}.html)
+[![Documentation](https://img.shields.io/badge/docs-passing-green)](https://alexandrainst.github.io/{{cookiecutter.project_name}})
 [![License](https://img.shields.io/github/license/alexandrainst/{{cookiecutter.project_name}})](https://github.com/alexandrainst/{{cookiecutter.project_name}}/blob/main/LICENSE)
 [![LastCommit](https://img.shields.io/github/last-commit/alexandrainst/{{cookiecutter.project_name}})](https://github.com/alexandrainst/{{cookiecutter.project_name}}/commits/main)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](https://github.com/alexandrainst/{{cookiecutter.project_name}}/blob/main/CODE_OF_CONDUCT.md)
@@ -62,8 +62,8 @@ The project includes the following convenience commands:
 - `make type-check`: Type check the code using `mypy`.
 - `make test`: Run tests using `pytest` and update the coverage badge in the readme.
 - `make docker`: Build a Docker image and run the Docker container.
-- `make docs`: Generate HTML documentation using `pdoc`.
-- `make view-docs`: View the generated HTML documentation in a browser.
+- `make docs`: View documentation locally in a browser.
+- `make publish-docs`: Publish documentation to GitHub Pages.
 - `make tree`: Show the project structure as a tree.
 
 
@@ -113,7 +113,8 @@ running `make docker`.
 ### Automatic Documentation
 
 Run `make docs` to create the documentation in the `docs` folder, which is based on
-your docstrings in your code. You can view this by running `make view-docs`.
+your docstrings in your code. You can publish this documentation to Github Pages by
+running `make publish-docs`.
 
 ### Automatic Test Coverage Calculation
 

diff --git a/{{cookiecutter.project_name}}/docs/.gitkeep b/{{cookiecutter.project_name}}/docs/.gitkeep
diff --git a/{{cookiecutter.project_name}}/docs/index.md b/{{cookiecutter.project_name}}/docs/index.md
@@ -0,0 +1 @@
+{% include-markdown "../README.md" %}
diff --git a/{{cookiecutter.project_name}}/makefile b/{{cookiecutter.project_name}}/makefile
@@ -78,20 +78,13 @@ add-repo-to-git:
 install-pre-commit:  ## Install pre-commit hooks
 	@uv run pre-commit install
 
-docs:  ## Generate documentation
-	@uv run pdoc --docformat google src/{{cookiecutter.project_name}} -o docs
-	@echo "Saved documentation."
-
-view-docs:  ## View documentation
-	@echo "Viewing API documentation..."
-	@uname=$$(uname); \
-		case $${uname} in \
-			(*Linux*) openCmd='xdg-open';; \
-			(*Darwin*) openCmd='open';; \
-			(*CYGWIN*) openCmd='cygstart';; \
-			(*) echo 'Error: Unsupported platform: $${uname}'; exit 2;; \
-		esac; \
-		"$${openCmd}" docs/{{ cookiecutter.project_name }}.html
+docs:  ## View documentation locally
+	@echo "Viewing documentation - run 'make publish-docs' to publish the documentation website."
+	@uv run mkdocs serve
+
+publish-docs:  ## Publish documentation to GitHub Pages
+	@uv run mkdocs gh-deploy
+	@echo "Updated documentation website: https://alexandrainst.github.io/ugens_elev"
 
 test:  ## Run tests
 	@uv run pytest && uv run readme-cov

diff --git a/{{cookiecutter.project_name}}/mkdocs.yaml b/{{cookiecutter.project_name}}/mkdocs.yaml
@@ -0,0 +1,8 @@
+site_name: {{ cookiecutter.project_name }}
+theme: material
+plugins:
+  - include-markdown
+  - search
+  - include_dir_to_nav
+nav:
+  - .
diff --git a/{{cookiecutter.project_name}}/pyproject.toml b/{{cookiecutter.project_name}}/pyproject.toml
@@ -32,13 +32,15 @@ dev-dependencies = [
     "pytest>={{ cookiecutter._pytest_version }}",
     "pytest-cov>={{ cookiecutter._pytest_cov_version }}",
     "pre-commit>={{ cookiecutter._pre_commit_version }}",
-    "pdoc>={{ cookiecutter._pdoc_version }}",
     "readme-coverage-badger>={{ cookiecutter._readme_coverage_badger_version }}",
     "click>={{ cookiecutter._click_version }}",
     "ruff>={{ cookiecutter._ruff_version }}",
     "mypy>={{ cookiecutter._mypy_version }}",
     "nbstripout>={{ cookiecutter._nbstripout_version }}",
     "coverage>={{ cookiecutter._coverage_version }}",
+    "mkdocs-material>={{ cookiecutter._mkdocs_material_version }}",
+    "mkdocs-include-markdown-plugin>={{ cookiecutter._mkdocs_plugin_include_markdown_version }}",
+    "mkdocs-include-dir-to-nav>={{ cookiecutter._mkdocs_plugin_include_dir_to_nav_version }}",
 ]
 
 [tool.ruff]