From 299b4954b36b3fb03e16a311fc683e40a948b5fb Mon Sep 17 00:00:00 2001
From: Martin van Hensbergen <martin.vanhensbergen@fox-it.com>
Date: Fri, 12 May 2023 11:23:44 +0200
Subject: [PATCH 1/2] Add documentation testing tooling

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

(DIS-1888)
---
 .gitignore           |  2 ++
 tests/docs/Makefile  | 24 ++++++++++++++++++++++++
 tests/docs/conf.py   | 34 ++++++++++++++++++++++++++++++++++
 tests/docs/index.rst |  8 ++++++++
 tox.ini              | 21 +++++++++++++++++++++
 5 files changed, 89 insertions(+)
 create mode 100644 tests/docs/Makefile
 create mode 100644 tests/docs/conf.py
 create mode 100644 tests/docs/index.rst

diff --git a/.gitignore b/.gitignore
index 9c1a2e8..74cecaf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,4 +6,6 @@ dist/
 *.pyc
 __pycache__/
 .pytest_cache/
+tests/docs/api
+tests/docs/build
 .tox/
diff --git a/tests/docs/Makefile b/tests/docs/Makefile
new file mode 100644
index 0000000..69e0098
--- /dev/null
+++ b/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)
diff --git a/tests/docs/conf.py b/tests/docs/conf.py
new file mode 100644
index 0000000..7ef62d3
--- /dev/null
+++ b/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
diff --git a/tests/docs/index.rst b/tests/docs/index.rst
new file mode 100644
index 0000000..ba16345
--- /dev/null
+++ b/tests/docs/index.rst
@@ -0,0 +1,8 @@
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    /api/*/*/index
diff --git a/tox.ini b/tox.ini
index 8c95722..98f71b0 100644
--- a/tox.ini
+++ b/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

From 77088d326231573a17ccca510dd8686eb79cf011 Mon Sep 17 00:00:00 2001
From: Martin van Hensbergen <martin.vanhensbergen@fox-it.com>
Date: Mon, 15 May 2023 13:25:55 +0200
Subject: [PATCH 2/2] Remove unnecessary newline from tox.ini

Make the formatting consistent with the other sections.
---
 tox.ini | 1 -
 1 file changed, 1 deletion(-)

diff --git a/tox.ini b/tox.ini
index 98f71b0..3426484 100644
--- a/tox.ini
+++ b/tox.ini
@@ -65,7 +65,6 @@ deps =
     sphinx-copybutton
     sphinx-design
     furo
-
 commands =
     make -C tests/docs clean
     make -C tests/docs html