Merge remote-tracking branch 'origin/develop'

Author: schroedk

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.8
+current_version = 0.0.9.dev0
 commit = False
 tag = False
 allow_dirty = False

.github/workflows/tox.yaml

@@ -1,4 +1,4 @@
-name: Merge develop, run tests and build docu
+name: Merge develop, run tests and build documentation
 
 on:
   pull_request:

.gitignore

@@ -7,6 +7,7 @@
 *.orig
 .tox
 docs/_build
+docs/sensai
 /sync.py
 dist
 *.egg-info*

build-docs.sh

@@ -0,0 +1,3 @@
+python build_scripts/update_docs.py
+sphinx-build -W -b html docs docs/build
+

build_scripts/update_docs.py

@@ -1,35 +1,32 @@
 #!/usr/bin/env python3
 import logging
 import os
-
-# This script is copy-pasted from a cookiecutter template (to be open sourced soon)
-# and therefore does not adhere to the code conventions for the remainder of sensAI
+import shutil
 
 
 log = logging.getLogger(os.path.basename(__file__))
 
 
-def module_template(module_path: str):
-    title = os.path.basename(module_path).replace("_", r"\_")
-    title = title[:-3]  # removing trailing .py
-    module_path = module_path[:-3]
+def module_template(module_qualname: str):
+    module_name = module_qualname.split(".")[-1]
+    title = module_name.replace("_", r"\_")
     template = f"""{title}
 {"="*len(title)}
 
-.. automodule:: {module_path.replace(os.path.sep, ".")}
+.. automodule:: {module_qualname}
    :members:
    :undoc-members:
 """
     return template
 
 
-def package_template(package_path: str):
-    package_name = os.path.basename(package_path)
+def package_template(package_qualname: str):
+    package_name = package_qualname.split(".")[-1]
     title = package_name.replace("_", r"\_")
     template = f"""{title}
 {"="*len(title)}
 
-.. automodule:: {package_path.replace(os.path.sep, ".")}
+.. automodule:: {package_qualname}
    :members:
    :undoc-members:
 
@@ -41,50 +38,80 @@ def package_template(package_path: str):
     return template
 
 
+def indexTemplate(package_name):
+    title = "Modules"
+    template = \
+        f"""{title}
+{"="*len(title)}
+
+.. automodule:: {package_name}
+   :members:
+   :undoc-members:
+
+.. toctree::
+   :glob:
+
+   *
+"""
+    return template
+
+
 def write_to_file(content: str, path: str):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
     with open(path, "w") as f:
         f.write(content)
     os.chmod(path, 0o666)
 
 
-def make_docu(basedir=os.path.join("src", "sensai"), overwrite=False):
+
+def make_rst(src_root=os.path.join("src", "sensai"), rst_root=os.path.join("docs", "sensai"), clean=False, overwrite=False):
     """
     Creates/updates documentation in form of rst files for modules and packages.
     Does not delete any existing rst files. Thus, rst files for packages or modules that have been removed or renamed
     should be deleted by hand.
 
     This method should be executed from the project's top-level directory
 
-    :param basedir: path to library basedir, typically "src/<library_name>"
+    :param src_root: path to library base directory, typically "src/<library_name>"
+    :param clean: whether to completely clean the target directory beforehand, removing any existing .rst files
     :param overwrite: whether to overwrite existing rst files. This should be used with caution as it will delete
         all manual changes to documentation files
     :return:
     """
-    library_basedir = basedir.split(os.path.sep, 1)[1]  # splitting off the "src" part
-    for file in os.listdir(basedir):
-        if file.startswith("_"):
-            continue
+    rst_root = os.path.abspath(rst_root)
 
-        library_file_path = os.path.join(library_basedir, file)
-        full_path = os.path.join(basedir, file)
-        file_name, ext = os.path.splitext(file)
-        docs_file_path = os.path.join("docs", library_basedir, f"{file_name}.rst")
-        if os.path.exists(docs_file_path) and not overwrite:
-            log.debug(f"{docs_file_path} already exists, skipping it")
-            if os.path.isdir(full_path):
-                make_docu(basedir=full_path, overwrite=overwrite)
+    if clean and os.path.isdir(rst_root):
+        shutil.rmtree(rst_root)
+
+    base_package_name = os.path.basename(src_root)
+    write_to_file(indexTemplate(base_package_name), os.path.join(rst_root, "index.rst"))
+
+    for root, dirnames, filenames in os.walk(src_root):
+        if os.path.basename(root).startswith("_"):
             continue
-        os.makedirs(os.path.dirname(docs_file_path), exist_ok=True)
+        base_package_relpath = os.path.relpath(root, start=src_root)
+        base_package_qualname = os.path.relpath(root, start=os.path.dirname(src_root)).replace(os.path.sep, ".")
+
+        for dirname in dirnames:
+            if not dirname.startswith("_"):
+                package_qualname = f"{base_package_qualname}.{dirname}"
+                package_rst_path = os.path.join(rst_root, base_package_relpath,  f"{dirname}.rst")
+                log.info(f"Writing package documentation to {package_rst_path}")
+                write_to_file(package_template(package_qualname), package_rst_path)
+
+        for filename in filenames:
+            base_name, ext = os.path.splitext(filename)
+            if ext == ".py" and not filename.startswith("_"):
+                module_qualname = f"{base_package_qualname}.{filename[:-3]}"
+
+                module_rst_path = os.path.join(rst_root, base_package_relpath, f"{base_name}.rst")
+                if os.path.exists(module_rst_path) and not overwrite:
+                    log.debug(f"{module_rst_path} already exists, skipping it")
 
-        if ext == ".py":
-            log.info(f"writing module docu to {docs_file_path}")
-            write_to_file(module_template(library_file_path), docs_file_path)
-        elif os.path.isdir(full_path):
-            log.info(f"writing package docu to {docs_file_path}")
-            write_to_file(package_template(library_file_path), docs_file_path)
-            make_docu(basedir=full_path, overwrite=overwrite)
+                log.info(f"Writing module documentation to {module_rst_path}")
+                write_to_file(module_template(module_qualname), module_rst_path)
 
 
 if __name__ == "__main__":
     logging.basicConfig(level=logging.INFO)
-    make_docu()
+    make_rst(clean=True)

docs/conf.py

@@ -117,7 +117,10 @@ def findLineFromObjectName(sourceFile, objectName):
     "MySQLdb",
     "catboost",
     "clearml",
-    "azure"
+    "azure",
+    "geopandas",
+    "shapely",
+    "networkx"
 ]
 
 # Render docu of __init__ methods