Fix issues with pdoc auto-generated documentation (missing objects, no docstrings for functions) (#443)

Author: Griger5

.github/workflows/pdoc.yml

@@ -26,6 +26,7 @@ jobs:
           python-version: 3.12
       - name: Build
         run: |
+          echo "PDOC_GENERATE_PYPARTMC_DOCS=True" >> $GITHUB_ENV
           pip install pdoc
           pip install -e .
           PDOC_ALLOW_EXEC=1 python -We -m pdoc -o html PyPartMC

src/PyPartMC/__init__.py

@@ -4,6 +4,7 @@
 
 #  pylint: disable=invalid-name
 import importlib.metadata
+import inspect
 
 # pylint: disable=invalid-name,wrong-import-position
 import os
@@ -79,8 +80,29 @@ def __generate_si():
     __versions_of_build_time_dependencies__,
 )
 
+# Hacky workaround for missing docs in pdoc auto-generated documentation.
+# After the switch to nanobind, the docs became empty despite "__doc__" being
+# accessible in all of PyPartMC's objects. The code below manually populates
+# the "__all__" atrribute of the package. Additionally, functions in the generated
+# docs would be listed as nanobind objects with no additional documentation.
+# To solve that, dummy functions of the same name are created, and their "__doc__"
+# attribute is manually set to the "original" objects' "__doc__"
+if os.getenv("PDOC_GENERATE_PYPARTMC_DOCS") == "True":
+    all_items = []
+    for name, obj in inspect.getmembers(
+        _PyPartMC  # pylint: disable=undefined-variable
+    ):
+        if callable(obj):
+            if not inspect.isclass(obj):
+                exec(name + " = lambda : 0")  # pylint: disable=exec-used
+                temp = "_PyPartMC." + name + ".__doc__"
+                setattr(eval(name), "__doc__", eval(temp))  # pylint: disable=eval-used
+            all_items.append(name)
+
+    __all__ = tuple([*all_items, "si"])
+
 __version__ = importlib.metadata.version(__package__)
 
-# walkaround for MATLAB bindings
+# workaround for MATLAB bindings
 # pylint: disable=undefined-variable
 setattr(nanobind, "nb_type_0", type(_PyPartMC.AeroData))

tests/test_help.py

@@ -0,0 +1,59 @@
+import inspect
+import pydoc
+
+import pytest
+
+import PyPartMC as ppmc
+
+
+@pytest.mark.parametrize(
+    "obj",
+    (
+        ppmc.AeroBinned,
+        ppmc.AeroData,
+        ppmc.AeroParticle,
+        ppmc.AeroState,
+        ppmc.CampCore,
+        ppmc.EnvState,
+        ppmc.GasData,
+        ppmc.GasState,
+        ppmc.Photolysis,
+        ppmc.RunExactOpt,
+        ppmc.RunPartOpt,
+        ppmc.RunSectOpt,
+        ppmc.Scenario,
+        ppmc.condense_equilib_particle,
+        ppmc.condense_equilib_particles,
+        ppmc.diam2rad,
+        ppmc.histogram_1d,
+        ppmc.histogram_2d,
+        ppmc.input_exact,
+        ppmc.input_sectional,
+        ppmc.input_state,
+        ppmc.loss_rate,
+        ppmc.loss_rate_dry_dep,
+        ppmc.output_state,
+        ppmc.pow2_above,
+        ppmc.rad2diam,
+        ppmc.rand_init,
+        ppmc.rand_normal,
+        ppmc.run_exact,
+        ppmc.run_part,
+        ppmc.run_part_timeblock,
+        ppmc.run_part_timestep,
+        ppmc.run_sect,
+        ppmc.sphere_rad2vol,
+        ppmc.sphere_vol2rad,
+    ),
+)
+def test_help_output(obj):
+    help_output = pydoc.render_doc(obj, renderer=pydoc.plaintext)
+
+    assert len(obj.__doc__) > 0
+
+    # help() output of functions is broken on CI
+    if inspect.isclass(obj):
+        # remove whitespace and bars
+        assert "".join(obj.__doc__.split()) in "".join(
+            help_output.replace("|", "").split()
+        )