Add "autodocs", code documentation generated from docstrings

Adding a new section into "Contribute" page, "Code documentation", and besides the actual code documenation, I propose moving "Classes" page there as well.
teemtee · May 26, 2023 · 4285f35 · 4285f35
1 parent 5e70c85
commit 4285f35
Show file tree

Hide file tree

Showing 7 changed files with 27 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 # tmt-specific
 
 /tmp/
+docs/autodocs/*.rst
 docs/_build
 docs/spec
 docs/stories

diff --git a/docs/Makefile b/docs/Makefile
@@ -19,18 +19,23 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext autodocs
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
+	@echo "  autodocs   to refresh autodocs generated files"
 
 clean:
 	rm -rf $(BUILDDIR)/*
 
+autodocs:
+	rm -f autodocs/*.rst
+	pushd ../ && sphinx-apidoc --force --implicit-namespaces --no-toc -o docs/autodocs tmt && popd
+
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo

diff --git a/docs/autodocs/.gitkeep b/docs/autodocs/.gitkeep
diff --git a/docs/classes.rst b/docs/classes.rst
@@ -424,5 +424,6 @@ Essential Classes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. automodule:: tmt
+    :noindex:
     :members:
     :undoc-members:
diff --git a/docs/conf.py b/docs/conf.py
@@ -50,6 +50,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc.typehints',
     'sphinx_rtd_theme',
     ]
 
@@ -126,6 +127,14 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# Autodocs & type hints
+autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'private-members']
+autoclass_content = "both"
+
+autodoc_typehints_format = 'short'
+autodoc_typehints_description_target = 'all'
+# This one works, but it's a bit uglier than the default value (`signature`).
+# autodoc_typehints = 'description'
 
 # -- Options for HTML output ----------------------------------------------
 

diff --git a/docs/contribute.rst b/docs/contribute.rst
@@ -384,3 +384,13 @@ __ https://bodhi.fedoraproject.org/releases/
 __ https://github.com/teemtee/tmt/releases/
 __ https://pypi.org/project/tmt/
 __ https://copr.fedorainfracloud.org/coprs/psss/tmt/builds/
+
+
+Code documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+    :maxdepth: 1
+
+    Overview of important and interesting classes <classes>
+    Documentation generated from sources <autodocs/tmt.rst>
diff --git a/docs/index.rst b/docs/index.rst
@@ -33,5 +33,4 @@ Table of Contents
     Stories <stories>
     Questions <questions>
     Contribute <contribute>
-    Classes <classes>
     Plugins <plugins>