Merge pull request #76 from boschglobal/69-duplicate-elements-in-navbar

fixes: #69
boschglobal · Nov 18, 2022 · f1ce6bb · f1ce6bb
2 parents 43fd6c6 + fc0406a
commit f1ce6bb
Show file tree

Hide file tree

Showing 40 changed files with 1,261 additions and 980 deletions.
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -21,7 +21,7 @@ SHELL [ "/bin/zsh", "-c" ]
 # set environment
 ENV PYTHONUNBUFFERED 1
 ENV TZ=Europe/Berlin
-ENV PATH="/home/vscode/.local/bin:${PATH}"
+ENV PATH="/root/.local/bin:${PATH}"
 
 # Install apt dependencies
 # - default-jre for running plantuml

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -21,7 +21,7 @@
       // Set *default* container specific settings.json values on container create.
       "settings": {
         "python.poetryPath": "/usr/local/py-utils/bin/poetry",
-        "python.defaultInterpreterPath": "${containerWorkspaceFolder}/.venv/bin/python",
+        //"python.defaultInterpreterPath": "${containerWorkspaceFolder}/.venv/bin/python",
         "python.analysis.extraPaths": [
           "${containerWorkspaceFolder}"
         ]
@@ -42,5 +42,5 @@
   // It's necessary to do this here because in Dockerfile we do not have the config files (pyproject.toml +
   // .pre-commit-config.yaml) available.
   //"postCreateCommand": "poetry config virtualenvs.create false && poetry lock && poetry install && pre-commit install --install-hooks"
-  "onCreateCommand": "poetry completions bash >> ~/.bash_completion && poetry config virtualenvs.in-project true && poetry install && pre-commit install --install-hooks"
+  //"onCreateCommand": "poetry completions bash >> ~/.bash_completion && poetry config virtualenvs.in-project true && poetry install && pre-commit install --install-hooks"
 }
diff --git a/.gitignore b/.gitignore
@@ -177,3 +177,8 @@ requirements.txt
 # Datasource local storage ignored files
 .idea/dataSources/
 .idea/dataSources.local.xml
+
+docs/doxygen/graphviz/
+demo/ocilib/
+demo/graphviz/
+tests/toc/*.rst
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -19,31 +19,45 @@
             ]
         },
         {
-            "name": "Debug: Doxysphinx Clean Command",
+            "name": "Debug: Doxysphinx Build Command Graphviz",
             "type": "python",
             "request": "launch",
             "cwd": "${workspaceFolder}",
             "module": "doxysphinx",
             "args": [
                 "--verbosity=DEBUG",
-                "clean",
+                "build",
                 "${workspaceFolder}",
                 "${workspaceFolder}/.build",
-                "${workspaceFolder}/demo/demo.doxyfile"
+                "${workspaceFolder}/docs/doxygen/graphviz"
             ]
         },
         {
-            "name": "Debug: Python Semantic Release",
+            "name": "Debug: Doxysphinx Clean Command",
             "type": "python",
             "request": "launch",
             "cwd": "${workspaceFolder}",
-            "program": "/home/vscode/.local/bin/semantic-release",
-            "justMyCode": false,
+            "module": "doxysphinx",
             "args": [
-                "publish",
                 "--verbosity=DEBUG",
-                "--noop"
+                "clean",
+                "${workspaceFolder}",
+                "${workspaceFolder}/.build",
+                "${workspaceFolder}/demo/demo.doxyfile"
             ]
         },
+        {
+            "name": "Python: Test Cases",
+            "type": "python",
+            "request": "launch",
+            "cwd": "${workspaceFolder}",
+            "purpose": [
+                "debug-test"
+            ],
+            "console": "integratedTerminal",
+            "env": {
+                "PYTEST_ADDOPTS": "--no-cov"
+            }
+        }
     ]
 }
diff --git a/Makefile b/Makefile
@@ -29,25 +29,45 @@ clean:
 	@poetry run doxysphinx --verbosity=DEBUG clean $(DOCS_SOURCE_DIR) $(BUILD_DIR)/html demo/demo.doxyfile
 # cannot use rm here because it's not portable (win/linux)
 	@poetry run python -c 'exec("import shutil\nimport glob\n\nfor result in glob.glob(\"docs/doxygen/demo/*\"): shutil.rmtree(result)")'
+	@poetry run python -c 'exec("import shutil\nimport glob\n\nfor result in glob.glob(\"docs/doxygen/graphviz/*\"): shutil.rmtree(result)")'
 	@poetry run python -c 'exec("import shutil\nimport glob\n\nfor result in glob.glob(\".build/*\"): shutil.rmtree(result)")'
 
-doxygen:
+
+# targets for demo project
+doxygen_demo:
 	@doxygen demo/demo.doxyfile
 
-doxysphinx:
+doxysphinx_demo:
 	@poetry run doxysphinx --verbosity=DEBUG build $(DOCS_SOURCE_DIR) $(BUILD_DIR)/html demo/demo.doxyfile
 
-doxysphinx_with_dir:
+doxysphinx_demo_with_dir:
 	@poetry run doxysphinx --verbosity=DEBUG build $(DOCS_SOURCE_DIR) $(BUILD_DIR)/html docs/doxygen/demo/html
 
+# targets for graphviz project
+# -> ATTENTION: Before you can use them you have to download graphviz (see ./demo/load_additional_demos.sh)
+doxygen_graphviz:
+	@cd demo/graphviz; doxygen Doxyfile.in
+
+doxysphinx_graphviz:
+	@mkdir -p docs/doxygen/graphviz
+	@cp -R demo/graphviz/doxygen/html docs/doxygen/graphviz
+	@poetry run doxysphinx --verbosity=DEBUG build $(DOCS_SOURCE_DIR) $(BUILD_DIR)/html docs/doxygen/graphviz/html
+
+# sphinx
 sphinx:
 	@poetry run sphinx-build -M html "$(DOCS_SOURCE_DIR)" "$(BUILD_DIR)" '--keep-going' '-j' 'auto' $(SPHINX_OPTS)
 
-profile: clean doxygen
+# for profiling...
+profile: clean doxygen_demo
 	@poetry run python -m cProfile -o .doxysphinx.prof doxysphinx/cli.py --verbosity=DEBUG build $(DOCS_SOURCE_DIR) $(BUILD_DIR) demo/demo.doxyfile
 	@poetry run snakeviz .doxysphinx.prof
 	@rm .doxysphinx.prof
 
+# some aliases
+doxygen: doxygen_demo
+
+doxysphinx: doxysphinx_demo
+
 html: doxygen doxysphinx sphinx
 	@echo ""
 	@echo "Build finished. The Documentation is in $(BUILD_DIR)/html."
diff --git a/NOTICE.md b/NOTICE.md
@@ -15,14 +15,14 @@ over code that is written for this project.
 
 How to add names to this file:
 
-```plain
+```text
 * Individual's name <submission email address>.
 ```
 
 If Individual's organization is copyright holder of her contributions add the
 organization's name, optionally also the contributor's name:
 
-```plain
+```text
 * Organization's name
   * Individual's name - <submission corporate email address>
 ```

diff --git a/conf.py b/conf.py
@@ -7,12 +7,15 @@
 #  - Markus Braun, :em engineering methods AG (contracted by Robert Bosch GmbH)
 # =====================================================================================
 """sphinx configuration file."""
+
+# pylint: disable=invalid-name
+
 import os
 import sys
 
 sys.path.append(os.path.abspath("."))
 
-from conf_utils import (  # noqa E402
+from conf_utils import (  # noqa E402, pylint: disable=wrong-import-position
     last_updated_from_git,
     multi_glob,
     theme_options,
@@ -47,15 +50,14 @@
     "dist",
     "demo",
     "docs/_templates",
+    "docs/auto_api/index.rst",
+    "NOTICE.md",
     "LICENSE.md",
     "CHANGELOG.md",
     "README.md",
     "external/README.md",
 )
 
-# The name of the Pygments (syntax highlighting) style to use.
-# pygments_style = 'sphinx'
-
 # -- Options for HTML output -------------------------------------------------
 # Configure HTML theme (remember to also change doxysphinx)
 # html_theme = "sphinx_rtd_theme"
@@ -73,14 +75,11 @@
 extensions = [
     "sphinxcontrib.needs",
     "sphinxcontrib.plantuml",
-    "sphinxcontrib.test_reports",
     "sphinx.ext.mathjax",
     "sphinx.ext.ifconfig",
-    "sphinx_toolbox.more_autodoc",
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
+    "autoapi.extension",
     "sphinx.ext.viewcode",
-    "sphinx_autodoc_typehints",
     "myst_parser",
     "matplotlib.sphinxext.plot_directive",
     "sphinx.ext.duration",
@@ -99,14 +98,13 @@
 plantuml = "java -Djava.awt.headless=true -jar /usr/share/plantuml/plantuml.jar"
 plantuml_output_format = "svg"
 
-# Autodoc
-primary_domain = "py"
-highlight_language = "python3"
-autodoc_default_options = {"members": True, "undoc-members": True}
-autodoc_member_order = "bysource"
-add_module_names = False
-autosummary_generate = True
-autosummary_generate_overwrite = False
+# Autoapi
+autoapi_dirs = ["doxysphinx"]
+autoapi_root = "docs/auto_api"
+autoapi_options = ["members", "undoc-members", "show-inheritance", "show-inheritance-diagram", "show-module-summary"]
+autoapi_keep_files = False
+autoapi_add_toctree_entry = False
+autodoc_typehints = "signature"
 
 # Myst
 myst_enable_extensions = ["colon_fence"]

diff --git a/conf_utils.py b/conf_utils.py
@@ -13,6 +13,8 @@
 import re
 from typing import Any, Dict, List
 
+# pylint: disable=all
+
 
 def version_from_project_toml() -> str:
     """Get the version number from project.toml file."""
@@ -62,13 +64,13 @@ def theme_options(theme: str) -> Dict[str, Any]:
 
     if theme == "sphinx_book_theme":
         return {
-            "collapse_navigation": False,
+            "show_navbar_depth": 1,
+            "collapse_navigation": True,
             "repository_url": "https://github.com/boschglobal/doxysphinx",
             "use_repository_button": True,
             "use_edit_page_button": True,
             "repository_branch": "main",
             "logo_only": True,
-            "show_navbar_depth": 5,
             "home_page_in_toc": True,
             "extra_navbar": '<div class="attribution">theme based on the '
             '<a href="https://sphinx-book-theme.readthedocs.io/">sphinx book theme</a> '
@@ -78,7 +80,8 @@ def theme_options(theme: str) -> Dict[str, Any]:
 
     elif theme == "sphinx_rtd_theme":
         return {
-            "collapse_navigation": False,
+            "show_nav_level": 1,
+            "collapse_navigation": True,
             "github_url": "https://github.com/boschglobal/doxysphinx",
             "repository_url": "https://github.com/boschglobal/doxysphinx",
             "logo_only": False,

diff --git a/demo/load_additional_demos.sh b/demo/load_additional_demos.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+# This script will load additional oss demo projects.
+
+# graphviz
+git clone --depth 1 https://gitlab.com/graphviz/graphviz.git
+rm -rf graphviz/.git # get rid of git repo...
+echo "" >> graphviz/Doxyfile.in
+echo "HTML_EXTRA_STYLESHEET = ../../external/doxygen-awesome-css/doxygen-awesome.css" >> graphviz/Doxyfile.in
+
+# for future use
+#git clone --depth 1 https://github.com/vrogier/ocilib.git
+#rm -rf ocilib/.git # get rid of git repo...
diff --git a/docs/_static/sphinx-book-theme-custom.css b/docs/_static/sphinx-book-theme-custom.css
@@ -48,3 +48,12 @@ body {
 p.rubric {
     border-bottom: none !important;
 }
+
+/* navigation bar color override */
+.bd-sidebar#site-navigation {
+    background: whitesmoke;
+}
+
+#search-input {
+    border-radius: .3em
+}
diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst