Add documentation testing tooling

Add tox commands to generate API documentation for previewing in browser and automatic checking of broken URLs.

(DIS-1888)

.gitignore

@@ -6,4 +6,6 @@ dist/
 *.pyc
 __pycache__/
 .pytest_cache/
+tests/docs/api
+tests/docs/build
 .tox/

tests/docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -jauto
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: clean help Makefile
+
+clean: Makefile
+	rm -rf api
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

tests/docs/conf.py

@@ -0,0 +1,34 @@
+extensions = [
+    "autoapi.extension",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.doctest",
+    "sphinx.ext.napoleon",
+    "sphinx_argparse_cli",
+]
+
+exclude_patterns = []
+
+html_theme = "furo"
+
+autoapi_type = "python"
+autoapi_dirs = ["../../dissect/"]
+autoapi_ignore = ["*tests*", "*.tox*", "*venv*", "*examples*"]
+autoapi_python_use_implicit_namespaces = True
+autoapi_add_toctree_entry = False
+autoapi_root = "api"
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-module-summary",
+    "special-members",
+    "imported-members",
+]
+autoapi_keep_files = True
+autoapi_template_dir = "_templates/autoapi"
+
+autodoc_typehints = "signature"
+autodoc_member_order = "groupwise"
+
+autosectionlabel_prefix_document = True

tests/docs/index.rst

@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    /api/*/*/index

tox.ini

@@ -55,3 +55,24 @@ extend-ignore =
     # See https://github.com/PyCQA/pycodestyle/issues/373
     E203,
 statistics = True
+
+[testenv:docs-build]
+allowlist_externals = make
+deps =
+    sphinx
+    sphinx-autoapi
+    sphinx_argparse_cli
+    sphinx-copybutton
+    sphinx-design
+    furo
+
+commands =
+    make -C tests/docs clean
+    make -C tests/docs html
+
+[testenv:docs-linkcheck]
+allowlist_externals = make
+deps = {[testenv:docs-build]deps}
+commands =
+    make -C tests/docs clean
+    make -C tests/docs linkcheck