docs(api): restructure api documentation for clarity

- Remove duplicate entries - Unnest navigation - Remove empty section
ing-bank · Aug 19, 2022 · affdd75 · affdd75
1 parent 709baa5
commit affdd75
Show file tree

Hide file tree

Showing 19 changed files with 117 additions and 160 deletions.
diff --git a/docs/autogenerate.sh b/docs/autogenerate.sh
@@ -5,8 +5,9 @@ rm -rf autogen
 mkdir -p source/_static autogen
 
 # auto-generate code documentation
-sphinx-apidoc -f -H POPMON -o autogen ../popmon
-mv autogen/modules.rst autogen/popmon_index.rst
+export SPHINX_APIDOC_OPTIONS="members,show-inheritance,ignore-module-all"
+sphinx-apidoc -f -M -H "API Documentation" -o autogen ../popmon
+mv autogen/modules.rst autogen/code.rst
 mv autogen/* source/ 
 
 # remove auto-gen directory

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,3 @@
 sphinx_rtd_theme
 myst_parser
+sphinx_autodoc_typehints
diff --git a/docs/source/code.rst b/docs/source/code.rst
@@ -2,6 +2,6 @@ API Documentation
 =================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 4
 
-   popmon_index
+   popmon
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -38,6 +38,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
+    "sphinx_autodoc_typehints",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -68,7 +69,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["*test*", "popmon.tutorials.*", "popmon.decorators.*"]
+exclude_patterns = ["*test*", "popmon.decorators.*"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
@@ -86,6 +87,9 @@
 
     html_theme = "sphinx_rtd_theme"
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+    html_theme_options = {
+        "navigation_depth": 8,
+    }
 # otherwise, readthedocs.org uses their theme by default, so no need to specify it
 
 # Add any paths that contain custom static files (such as style sheets) here,

diff --git a/docs/source/popmon.alerting.rst b/docs/source/popmon.alerting.rst
@@ -1,6 +1,11 @@
 popmon.alerting package
 =======================
 
+.. automodule:: popmon.alerting
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,21 +14,13 @@ popmon.alerting.alerts\_summary module
 
 .. automodule:: popmon.alerting.alerts_summary
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.alerting.compute\_tl\_bounds module
 ------------------------------------------
 
 .. automodule:: popmon.alerting.compute_tl_bounds
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.alerting
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.analysis.comparison.rst b/docs/source/popmon.analysis.comparison.rst
@@ -1,6 +1,11 @@
 popmon.analysis.comparison package
 ==================================
 
+.. automodule:: popmon.analysis.comparison
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,21 +14,13 @@ popmon.analysis.comparison.comparisons module
 
 .. automodule:: popmon.analysis.comparison.comparisons
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.comparison.hist\_comparer module
 ------------------------------------------------
 
 .. automodule:: popmon.analysis.comparison.hist_comparer
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.analysis.comparison
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.analysis.profiling.rst b/docs/source/popmon.analysis.profiling.rst
@@ -1,6 +1,11 @@
 popmon.analysis.profiling package
 =================================
 
+.. automodule:: popmon.analysis.profiling
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,29 +14,21 @@ popmon.analysis.profiling.hist\_profiler module
 
 .. automodule:: popmon.analysis.profiling.hist_profiler
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.profiling.profiles module
 -----------------------------------------
 
 .. automodule:: popmon.analysis.profiling.profiles
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.profiling.pull\_calculator module
 -------------------------------------------------
 
 .. automodule:: popmon.analysis.profiling.pull_calculator
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.analysis.profiling
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.analysis.rst b/docs/source/popmon.analysis.rst
@@ -1,6 +1,11 @@
 popmon.analysis package
 =======================
 
+.. automodule:: popmon.analysis
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Subpackages
 -----------
 
@@ -18,37 +23,29 @@ popmon.analysis.apply\_func module
 
 .. automodule:: popmon.analysis.apply_func
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.functions module
 --------------------------------
 
 .. automodule:: popmon.analysis.functions
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.hist\_numpy module
 ----------------------------------
 
 .. automodule:: popmon.analysis.hist_numpy
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.analysis.merge\_statistics module
 ----------------------------------------
 
 .. automodule:: popmon.analysis.merge_statistics
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.analysis
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.base.rst b/docs/source/popmon.base.rst
@@ -1,6 +1,11 @@
 popmon.base package
 ===================
 
+.. automodule:: popmon.base
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,29 +14,21 @@ popmon.base.module module
 
 .. automodule:: popmon.base.module
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.base.pipeline module
 ---------------------------
 
 .. automodule:: popmon.base.pipeline
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.base.registry module
 ---------------------------
 
 .. automodule:: popmon.base.registry
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.base
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.decorators.rst b/docs/source/popmon.decorators.rst
@@ -1,6 +1,11 @@
 popmon.decorators package
 =========================
 
+.. automodule:: popmon.decorators
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,21 +14,13 @@ popmon.decorators.pandas module
 
 .. automodule:: popmon.decorators.pandas
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.decorators.spark module
 ------------------------------
 
 .. automodule:: popmon.decorators.spark
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.decorators
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.hist.filling.rst b/docs/source/popmon.hist.filling.rst
@@ -1,10 +1,7 @@
 popmon.hist.filling package
 ===========================
 
-Module contents
----------------
-
 .. automodule:: popmon.hist.filling
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.hist.rst b/docs/source/popmon.hist.rst
@@ -1,6 +1,11 @@
 popmon.hist package
 ===================
 
+.. automodule:: popmon.hist
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Subpackages
 -----------
 
@@ -17,21 +22,13 @@ popmon.hist.hist\_splitter module
 
 .. automodule:: popmon.hist.hist_splitter
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.hist.hist\_utils module
 ------------------------------
 
 .. automodule:: popmon.hist.hist_utils
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.hist
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
diff --git a/docs/source/popmon.io.rst b/docs/source/popmon.io.rst
@@ -1,6 +1,11 @@
 popmon.io package
 =================
 
+.. automodule:: popmon.io
+   :members:
+   :show-inheritance:
+   :ignore-module-all:
+
 Submodules
 ----------
 
@@ -9,29 +14,21 @@ popmon.io.file\_reader module
 
 .. automodule:: popmon.io.file_reader
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.io.file\_writer module
 -----------------------------
 
 .. automodule:: popmon.io.file_writer
    :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all:
 
 popmon.io.json\_reader module
 -----------------------------
 
 .. automodule:: popmon.io.json_reader
    :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: popmon.io
-   :members:
-   :undoc-members:
    :show-inheritance:
+   :ignore-module-all: