#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"]

src/ifcopenshell-python/docs/ifcopenshell-python.rst

@@ -8,8 +8,8 @@ this document.
    :maxdepth: 1
    :caption: Contents:
 
-   ifcopenshell-python/quickstart
-   ifcopenshell-python/api-documentation
+   ifcopenshell-python/hello_world
+   ifcopenshell-python/developer_guide
 
 Indices and tables
 ------------------

src/ifcopenshell-python/docs/ifcopenshell-python/api-documentation.rst

@@ -1,21 +0,0 @@
-API Documentation
-=================
-
-.. automodule:: ifcopenshell.entity_instance
-   :members:
-
-.. automodule:: ifcopenshell.file
-   :members:
-
-.. automodule:: ifcopenshell.guid
-   :members:
-
-
-.. automodule:: ifcopenshell.template
-   :members:
-
-.. automodule:: ifcopenshell.validate
-   :members:
-
-.. automodule:: ifcopenshell.ids
-   :members:

src/ifcopenshell-python/docs/ifcopenshell-python/developer_guide.rst

@@ -0,0 +1,15 @@
+Developer Guide
+===============
+
+The core module implements low-level functionality to read and write IFC data. This includes:
+
+- Reading IFC data from different serialisations into Python objects
+- Accessing direct and indirect attributes of IFC entities
+- Creating IFC entities
+- Generating GlobalIds
+- Removing IFC entities and all references
+- Modifying IFC direct attributes
+- Checking IFC class inheritance
+- Validating IFC data
+
+TODO

src/ifcopenshell-python/docs/ifcopenshell-python/hello_world.rst

@@ -1,5 +1,7 @@
-Quickstart
-==========
+Hello, world!
+=============
 
 For starters, you can read `Using IfcOpenShell to parse IFC files with Python
 <https://thinkmoult.com/using-ifcopenshell-parse-ifc-files-python.html>`_
+
+TODO

src/ifcopenshell-python/docs/index.rst

@@ -1,20 +1,20 @@
 Let's learn IfcOpenShell
 ========================
 
-IfcOpenShell is a 
+IfcOpenShell is a suite of developer libraries and utilities to manipulate OpenBIM data.
 
-A coloured icon: :octicon:`report;1em;sd-text-info`, some more text.
+.. note::
 
-:bdg:`plain badge`
+   This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
 
 .. toctree::
+   :hidden:
    :maxdepth: 1
    :caption: Contents:
 
    ifcopenshell
    ifcopenshell-python
    ifcconvert
-   blenderbim
    bimtester
    ifcdiff
    ifcclash