#2185 Set up auto generated API reference documentation via sphinx-autoapi

src/ifcopenshell-python/docs/conf.py

@@ -28,19 +28,19 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 
 # -- Project information -----------------------------------------------------
 
 project = "IfcOpenShell"
-copyright = "2020, IfcOpenShell Contributors"
+copyright = "2020-2022, IfcOpenShell Contributors"
 author = "IfcOpenShell Contributors"
 
 # The full version, including alpha/beta/rc tags
-release = "0.0.1"
+release = "0.7.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -48,7 +48,34 @@ release = "0.0.1"
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.autodoc"]
+
+# I considered autodoc+autosummary but it had showstopper glitches:
+# - Some modules couldn't be accessed https://github.com/sphinx-doc/sphinx/issues/7912#issuecomment-1120508738
+# - No subnav making it really hard to navigate
+# - Kinda hacky setup https://stackoverflow.com/questions/2701998/sphinx-autodoc-is-not-automatic-enough
+# - I couldn't customise the template to show submodules above members which makes API discovery hard for users
+extensions = ["autoapi.extension"]
+
+# We're only documenting Python here
+autoapi_type = 'python'
+
+# autoapi works by reading source code instead of importing modules
+autoapi_dirs = ['../ifcopenshell']
+
+# autoapi_options doesn't have show-module-summary, as it tends to create one
+# page per function which contradicts the presentation of showing all functions
+# as a list. This creates two possible locations where a function is documented
+# which is really disorienting. I also exclude imported-members. For example,
+# ifcopenshell.file is imported from ifcopenshell.file.file, but it gets pretty
+# confusing to see the docs again in multiple places (seriously,
+# ifcopenshell.file.file is everywhere).
+autoapi_options = ['members', 'undoc-members', 'private-members', 'special-members', 'show-inheritance']
+
+# This option is set to both to allow both class docstrings and __init__ docstrings.
+autoapi_python_class_content = 'both'
+
+# Group by type (e.g. attribute, class, function, etc) then alphabetically.
+autoapi_member_order = "groupwise"
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]