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..3426484 100644 --- a/tox.ini +++ b/tox.ini @@ -55,3 +55,23 @@ 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