DOC: add example module for autodoc

doc/conf.py

@@ -125,6 +125,16 @@
     'sphinx': ('https://www.sphinx-doc.org/', None),
 }
 
+# -- Set path for example_module.py -------------------------------------------
+
+# Normally, this is not necessary, because you should properly install
+# your Python module before running Sphinx.
+
+import os
+import sys
+
+sys.path.append(os.path.abspath('.'))
+
 # -- Get version information from Git -----------------------------------------
 
 try:

doc/example_module.py

@@ -0,0 +1,23 @@
+"""Module docstring."""
+
+
+def a_very_useful_function(one, two, three, four=3):
+    """This is one of the most useful functions.
+
+    :param str one: First argument
+    :param int two: Second argument
+    :param float three: Third argument
+    :param four: Fourth argument
+    :type four: integer or None
+
+    """
+
+
+class TheBestClass:
+    """This is a class."""
+
+    def __init__(self, value=4):
+        """This is the constructor."""
+
+    def multiplicate(self, factor):
+        """Scale the thing."""

doc/showcase/api-doc.rst

@@ -388,16 +388,30 @@ A link: :func:`insipid_sphinx_theme.setup`.
 .. automodule:: insipid_sphinx_theme
     :members:
 
+****
+
+.. automodule:: example_module
+    :members:
+
+
 ``sphinx.ext.autosummary``
 --------------------------
 
+.. warning::
+
+    With ``docutils`` versions older than 0.18, the HTML line breaks in the left
+    column are not working correctly.  Make sure to use at least
+    ``docutils >= 0.18``, which is supported since Sphinx version 5.0.
+
 .. autosummary::
 
-   setup
+    a_very_useful_function
+    TheBestClass
 
 ``:nosignatures:``
 
 .. autosummary::
-   :nosignatures:
+    :nosignatures:
 
-   setup
+    a_very_useful_function
+    TheBestClass