WIP sphinx docs - initial local build working

Author: jantman

CONTRIBUTING.md

@@ -71,6 +71,20 @@ $ nox --session=pre-commit
 Unit tests are located in the [tests/](tests/) directory,
 and are written using the [pytest](https://pytest.readthedocs.io/) testing framework.
 
+## How to build docs
+
+To build docs, serve them locally, and rebuild as they change:
+
+```console
+$ nox --session=docs
+```
+
+To just build docs to [docs/build/](docs/build/):
+
+```console
+$ nox --non-interactive --session=docs
+```
+
 ## How to submit changes
 
 Open a [pull request](https://github.com/jantman/machine_access_control/pulls) to submit changes to this project.

docs/Makefile

@@ -0,0 +1,54 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+VENV = .venv
+export VIRTUAL_ENV := $(abspath ${VENV})
+export PATH := ${VIRTUAL_ENV}/bin:${PATH}
+export GIT_COMMIT := $(shell git rev-parse --short HEAD)
+export GITURL := $(shell git config remote.origin.url)
+export BRANCH_NAME := $(shell git rev-parse --abbrev-ref HEAD)
+# TODO: update the proper git URL here:
+ifneq "$(GITURL)" "[email protected]:jantman/machine-access-control.git"
+	export GIT_COMMIT := ${GIT_COMMIT} (branch '${BRANCH_NAME}' from $(GITURL))
+endif
+
+${VENV}:
+	python3 -mvenv $@;
+
+setup: ${VENV}
+    # pin docutils due to bug: https://stackoverflow.com/questions/67542699/readthedocs-sphinx-not-rendering-bullet-list-from-rst-file
+	. .venv/bin/activate; python3 -m pip install -r requirements.txt
+
+ghp: setup
+	# WARNING - there aren't any checks to prevent someone with appropriate permissions
+	# from pushing their local build directly to the live docs. Don't copy this pattern!
+	@echo giturl is $(GITURL)
+	cd build/dirhtml && \
+		git init && \
+		git remote add origin $(GITURL) && \
+		git checkout -b gh-pages && \
+		git add --all && \
+		git commit -m "local docs build" && \
+		git push -f origin HEAD:gh-pages
+
+.PHONY: help setup all
+
+html: setup
+	. .venv/bin/activate; python3 -msphinx "$(SOURCEDIR)" "$(BUILDDIR)/html" -b html -E -W
+
+all: clean html
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: all

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx==7.4.7
+sphinx_rtd_theme==2.0.0
+sphinx-autobuild==2024.4.16
+sphinx-last-updated-by-git==0.3.7

docs/source/_static/theme_overrides.css

@@ -0,0 +1,13 @@
+/* thanks to: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+  .wy-table-responsive table td {
+    /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+    white-space: normal !important;
+  }
+
+  .wy-table-responsive {
+    overflow: visible !important;
+  }
+}

docs/source/conf.py

@@ -0,0 +1,61 @@
+"""Configuration file for the Sphinx documentation builder.
+
+For the full list of built-in configuration values, see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+import os
+from urllib.parse import urlparse
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "machine-access-control"
+copyright = "2024, Jason Antman"
+author = "Jason Antman"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.githubpages",
+    "sphinx.ext.todo",
+    "sphinx.ext.intersphinx",
+    "sphinx_last_updated_by_git",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+    "sticky_navigation": False,
+}
+html_static_path = ["_static"]
+
+html_context = {"theme_vcs_pageview_mode": "edit", "conf_py_path": "/source/"}
+
+if os.environ.get("GITHUB_ACTIONS") == "true":
+    html_context["display_github"] = True
+    html_context["github_user"], html_context["github_repo"] = os.environ[
+        "GITHUB_REPOSITORY"
+    ].split("/")
+    html_context["github_host"] = urlparse(os.environ["GITHUB_API_URL"]).hostname
+    html_context["github_version"] = os.environ.get(
+        "GITHUB_REF_NAME",
+        os.environ.get("GITHUB_HEAD_REF", os.environ.get("GITHUB_SHA")),
+    )
+
+html_css_files = [
+    # thanks to: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
+    "theme_overrides.css"  # override wide tables in RTD theme
+]

docs/source/index.rst

@@ -0,0 +1,20 @@
+.. machine-access-control documentation master file, created by
+   sphinx-quickstart on Sun Aug  4 15:42:24 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to machine-access-control's documentation!
+==================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

noxfile.py

@@ -2,6 +2,7 @@
 
 import os
 import shlex
+import shutil
 import sys
 from pathlib import Path
 from textwrap import dedent
@@ -197,3 +198,23 @@ def typeguard(session: Session) -> None:
     session.install(".")
     session.install("pytest", "typeguard", "pygments")
     session.run("pytest", f"--typeguard-packages={package}", *session.posargs)
+
+
+@session(python=python_versions[0], reuse_venv=True)
+def docs(session: Session) -> None:
+    """Build the documentation."""
+    args = session.posargs or ["-b", "html", "docs/source", "docs/build", "-E", "-W"]
+
+    if session.interactive and not session.posargs:
+        args = ["-a", "--watch=docs/source/_static", "--open-browser", *args]
+
+    builddir = Path("docs", "build")
+    if builddir.exists():
+        shutil.rmtree(builddir)
+
+    session.install("-r", "docs/requirements.txt")
+
+    if session.interactive:
+        session.run("sphinx-autobuild", *args)
+    else:
+        session.run("sphinx-build", *args)

poetry.lock

@@ -47,6 +47,8 @@ typeguard = ">=2.13.3"
 
 [tool.poetry.group.dev.dependencies]
 pytest-blockage = "^0.2.4"
+sphinx = "<8.0"
+sphinx-rtd-theme = "^2.0.0"
 
 [tool.coverage.paths]
 source = ["src", "*/site-packages"]