Merge pull request #303 from openego/feature/auto_sphinx_api

Adding sphinx autoapi
openego · Mar 24, 2023 · d85968d · d85968d
2 parents e04a4d8 + 038faaf
commit d85968d
Show file tree

Hide file tree

Showing 13 changed files with 38 additions and 328 deletions.
diff --git a/doc/api.rst b/doc/api.rst
diff --git a/doc/api/edisgo.flex_opt.rst b/doc/api/edisgo.flex_opt.rst
diff --git a/doc/api/edisgo.io.rst b/doc/api/edisgo.io.rst
diff --git a/doc/api/edisgo.network.rst b/doc/api/edisgo.network.rst
diff --git a/doc/api/edisgo.opf.rst b/doc/api/edisgo.opf.rst
diff --git a/doc/api/edisgo.tools.rst b/doc/api/edisgo.tools.rst
diff --git a/doc/api/edisgo_class.rst b/doc/api/edisgo_class.rst
diff --git a/doc/conf.py b/doc/conf.py
@@ -46,6 +46,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autoapi.extension",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -55,7 +56,36 @@
     "sphinx.ext.napoleon",  # enable Napoleon Sphinx v>1.3
     "sphinx.ext.extlinks",  # enables external links with a key
     "sphinx_autodoc_typehints",
+    "sphinx.ext.inheritance_diagram",
 ]
+# Autoapi settings
+autoapi_type = "python"
+autoapi_dirs = ["../edisgo"]
+autoapi_options = [
+    "members",
+    "undoc-members",
+    "show-inheritance",
+    "show-inheritance-diagram",
+    "show-module-summary",
+    "special-members",
+]
+# Files to ignore when building api documentation
+autoapi_ignore = [
+    "*/flex_opt/curtailment.py",
+    "*/flex_opt/storage_positioning.py",
+    "*/opf/*",
+]
+
+
+def skip_autoapi_parts(app, what, name, obj, skip, options):
+    if obj.type == "data":
+        skip = True
+    return skip
+
+
+def setup(sphinx):
+    sphinx.connect("autoapi-skip-member", skip_autoapi_parts)
+
 
 # Napoleon settings
 napoleon_google_docstring = True

diff --git a/doc/dev_notes.rst b/doc/dev_notes.rst
@@ -70,22 +70,15 @@ Code standards
 Documentation
 -------------
 
-Build the docs locally by first setting up the sphinx environment with (executed
-from top-level folder)
+You can build the docs locally as follows (executed from top-level eDisGo directory):
 
 .. code-block:: bash
 
-    sphinx-apidoc -f -o doc/api edisgo
+    sphinx-build -E -a -b html ./doc/ <outputdir>
 
-And then you build the html docs on your computer with
+To manually check if external links in the documentation work, you can run the following command (internal links are not checked by this):
 
 .. code-block:: bash
 
-    sphinx-build -E -a doc/ doc/_html
+   sphinx-build ./doc/ -b linkcheck -d _build/doctrees _build/html
 
-To manually check if external links in the documentation work, change into the doc
-repository and run the following command (internal links are not checked by this):
-
-.. code-block:: bash
-
-   sphinx-build . -b linkcheck -d _build/doctrees _build/html