_docs_tools

Makefile

@@ -51,8 +51,8 @@ test: ## Run test suite
 # ----------------------------
 .PHONY: build clean clean-preview install
 
-build: clean deps ## Build distribution package
-	$(PYTHON) -m build
+# build: clean deps ## Build distribution package
+# 	packaging/flatpak/build_flatpak.sh
 
 clean: ## Remove items from CLEANUP section in .gitignore
 	@tmpfile=$$(mktemp); \

docs/README.md

@@ -0,0 +1,4 @@
+# Project Documentation
+
+
+

docs/_docs_tools/Makefile

@@ -0,0 +1,26 @@
+.PHONY: clean delete api all
+
+clean: ## Clean up all build outputs
+	./cleanup.sh
+
+delete: ## delete up all generated docs
+	./cleanup.sh --outputs
+
+api: delete ## Generate an API-Reference website from source code at /docs/API-Reference
+	./build_api_ref.sh; \
+	./cleanup.sh
+
+
+all: ## Generate a website containing the API reference as well as other markdown docs
+	./build_api_ref.sh; \
+	./build_full_html.sh; \
+	./cleanup.sh
+
+# ----------------------------
+# Help
+# ----------------------------
+.PHONY: help
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
+

docs/_docs_tools/README.md

@@ -0,0 +1,31 @@
+# Docs Tools
+_a set of tools for generating and processing documentation_
+
+## Docs Processing Commands
+
+Get an overview of available docs processing tools:
+```sh
+make help
+```
+
+## Documentation Components
+
+### Markdown Docs
+
+This project's `/docs` folder contains hand-written documentation in markdown format.
+
+### API-Reference
+
+The `/docs/API-Reference` is an HTML website generated from the source code's docstrings using `sphinx`.
+
+```sh
+make api
+```
+
+### Full Docs HTML Website
+
+A website can be generated at `/docs/html` including both the API-Reference and the hand-written documentation.
+
+```sh
+make all
+```

docs/_docs_tools/build_api_ref.sh

@@ -0,0 +1,13 @@
+#!/bin/bash
+
+set -e # Exit if any command fails
+
+# the absolute paths of this script and it's directory
+SCRIPT_PATH=$(realpath -s "$0")
+SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
+cd $SCRIPT_DIR
+
+source ${SCRIPT_DIR}/paths.sh
+
+sphinx-apidoc -o $API_REF_TEMPLATE -e $SRC_DIR
+sphinx-build -b html $API_REF_TEMPLATE $OUTPUT_API

docs/_docs_tools/build_full_html.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+
+set -e # Exit if any command fails
+
+# the absolute paths of this script and it's directory
+SCRIPT_PATH=$(realpath -s "$0")
+SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
+cd $SCRIPT_DIR
+
+source ${SCRIPT_DIR}/paths.sh
+
+mkdir -p "$BUILD_DIR"
+
+## COPY FILES
+# Find all subfolders of $DOCS_DIR that contain README.md and don't start with "_"
+for dir in "$DOCS_DIR"/*/; do
+    folder_name=$(basename "$dir")
+    if [[ -f "$dir/README.md" && "$folder_name" != _* ]]; then
+        echo "Copying $folder_name..."
+        cp -r "$dir" "$BUILD_DIR/"
+    fi
+done
+
+cp -r $SPHINX_CONF_DIR/* "$BUILD_DIR"
+
+## Generate Docs
+sphinx-build -b html $BUILD_DIR $OUTPUT_FULL
+
+rm -r $BUILD_DIR

docs/_docs_tools/cleanup.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+
+
+# the absolute paths of this script and it's directory
+SCRIPT_PATH=$(realpath -s "$0")
+SCRIPT_DIR=$(dirname "$SCRIPT_PATH")
+cd $SCRIPT_DIR
+
+source ${SCRIPT_DIR}/paths.sh
+
+rm -r $BUILD_DIR >/dev/null 2>&1
+rm -r $API_REF_TEMPLATE/*.rst >/dev/null 2>&1
+
+if [ "$1" = "--outputs" ]; then
+  echo "deleting outputs..."
+  rm -r $OUTPUT_FULL >/dev/null 2>&1
+  rm -r $OUTPUT_API >/dev/null 2>&1
+fi
+exit 0

docs/_docs_tools/paths.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# the absolute paths of this script and it's directory
+SCRIPT_DIR="$( cd -- "$(dirname "$0")" >/dev/null 2>&1 ; pwd -P )"
+
+cd "$SCRIPT_DIR"
+
+BUILD_DIR="${SCRIPT_DIR}/_build"
+DOCS_DIR=$(realpath "$SCRIPT_DIR/..")
+SRC_DIR=$(realpath "$SCRIPT_DIR/../../src")
+OUTPUT_FULL="${DOCS_DIR}/html"
+OUTPUT_API="${DOCS_DIR}/API-Reference"
+
+# Path to the folder with stubs generated py sphinx-apidoc
+SPHINX_CONF_DIR=${SCRIPT_DIR}/sphinx_config
+API_REF_TEMPLATE=${SPHINX_CONF_DIR}/API-Reference
+

docs/_docs_tools/sphinx_config/API-Reference/README.md

@@ -0,0 +1,10 @@
+# API Reference
+
+```{toctree}
+:maxdepth: 1
+
+module1.submodule
+module1.submodule2
+module2.submodule2
+
+```

docs/_docs_tools/sphinx_config/API-Reference/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+
+import tomllib  # Python 3.11+; for 3.10 use `tomli`
+import os
+import sys
+from pathlib import Path
+
+# Add your source directory to sys.path for autodoc
+project_root = Path(__file__).resolve().parent.parent.parent.parent.parent
+sys.path.insert(0, str(project_root / "src"))
+
+# --------------------------------------------------
+# Load project metadata from pyproject.toml
+# --------------------------------------------------
+
+with open(project_root / "pyproject.toml", "rb") as f:
+    pyproject = tomllib.load(f)
+
+meta = pyproject.get("project") or pyproject.get("tool", {}).get("poetry", {})
+
+project = meta.get("name", "ProjectTemplate")
+authors = meta.get("authors", [])
+if isinstance(authors[0], dict):
+    authors = [item["name"] for item in authors]
+print(authors)
+author = (
+    ", ".join(authors)
+    if isinstance(meta.get("authors"), list)
+    else meta.get("author", "Unknown")
+)
+release = meta.get("version", "0.0.0")
+
+# --------------------------------------------------
+# General configuration
+# --------------------------------------------------
+extensions = [
+    "myst_parser",  # Markdown support
+    "sphinx.ext.autodoc",  # API docs from docstrings
+    "sphinx.ext.napoleon",  # Google/NumPy style docstrings
+    "sphinx.ext.viewcode",  # Link to highlighted source code
+]
+
+# Allow both .rst and .md as source files
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# The master toctree document (can be index.md)
+master_doc = "README"
+
+# --------------------------------------------------
+# HTML output
+# --------------------------------------------------
+html_theme = "furo"
+
+# Custom static files (CSS, JS) — optional
+html_static_path = ["_static"]
+
+# Example: add a custom CSS file
+# html_css_files = ["custom.css"]

docs/_docs_tools/sphinx_config/README.md

@@ -0,0 +1,20 @@
+# Walytis Documentation
+
+_where to find different parts of Walytis' documentation_
+
+## How It Works
+
+Most of Walytis' documentation lives in a dedicated repository:
+- https://github.com/emendir/WalytisTechnologies/blob/master/Walytis/DocsOverview.md
+
+## API Reference
+
+You can find the walytis_beta_api library's API reference here:
+
+
+```{toctree}
+:maxdepth: 2
+:glob:
+
+*/README
+```

docs/_docs_tools/sphinx_config/conf.py

@@ -0,0 +1,61 @@
+# Configuration file for the Sphinx documentation builder.
+
+import tomllib  # Python 3.11+; for 3.10 use `tomli`
+import os
+import sys
+from pathlib import Path
+
+# Add your source directory to sys.path for autodoc
+project_root = Path(__file__).resolve().parent.parent.parent.parent
+sys.path.insert(0, str(project_root / "src"))
+
+# --------------------------------------------------
+# Load project metadata from pyproject.toml
+# --------------------------------------------------
+
+with open(project_root / "pyproject.toml", "rb") as f:
+    pyproject = tomllib.load(f)
+
+meta = pyproject.get("project") or pyproject.get("tool", {}).get("poetry", {})
+
+project = meta.get("name", "ProjectTemplate")
+authors = meta.get("authors", [])
+if isinstance(authors[0], dict):
+    authors = [item["name"] for item in authors]
+print(authors)
+author = (
+    ", ".join(authors)
+    if isinstance(meta.get("authors"), list)
+    else meta.get("author", "Unknown")
+)
+release = meta.get("version", "0.0.0")
+
+# --------------------------------------------------
+# General configuration
+# --------------------------------------------------
+extensions = [
+    "myst_parser",  # Markdown support
+    "sphinx.ext.autodoc",  # API docs from docstrings
+    "sphinx.ext.napoleon",  # Google/NumPy style docstrings
+    "sphinx.ext.viewcode",  # Link to highlighted source code
+]
+
+# Allow both .rst and .md as source files
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# The master toctree document (can be index.md)
+master_doc = "README"
+
+# --------------------------------------------------
+# HTML output
+# --------------------------------------------------
+html_theme = "furo"
+
+# Custom static files (CSS, JS) — optional
+html_static_path = ["_static"]
+
+# Example: add a custom CSS file
+# html_css_files = ["custom.css"]