@bluedynamics/cdk8s-plone 0.1.5 → 0.1.6

package/documentation/Makefile

@@ -0,0 +1,357 @@
+##############################################################################
+# THIS FILE IS GENERATED BY MXMAKE
+#
+# DOMAINS:
+#: core.base
+#: core.mxenv
+#: docs.sphinx
+#
+# SETTINGS (ALL CHANGES MADE BELOW SETTINGS WILL BE LOST)
+##############################################################################
+
+## core.base
+
+# `deploy` target dependencies.
+# No default value.
+DEPLOY_TARGETS?=
+
+# target to be executed when calling `make run`
+# No default value.
+RUN_TARGET?=
+
+# Additional files and folders to remove when running clean target
+# No default value.
+CLEAN_FS?=
+
+# Optional makefile to include before default targets. This can
+# be used to provide custom targets or hook up to existing targets.
+# Default: include.mk
+INCLUDE_MAKEFILE?=include.mk
+
+# Optional additional directories to be added to PATH in format
+# `/path/to/dir/:/path/to/other/dir`. Gets inserted first, thus gets searched
+# first.
+# No default value.
+EXTRA_PATH?=
+
+# Path to Python project relative to Makefile (repository root).
+# Leave empty if Python project is in the same directory as Makefile.
+# For monorepo setups, set to subdirectory name (e.g., `backend`).
+# Future-proofed for multi-language monorepos (e.g., PROJECT_PATH_NODEJS).
+# No default value.
+PROJECT_PATH_PYTHON?=
+
+## core.mxenv
+
+# Primary Python interpreter to use. It is used to create the
+# virtual environment if `VENV_ENABLED` and `VENV_CREATE` are set to `true`.
+# If global `uv` is used, this value is passed as `--python VALUE` to the venv creation.
+# uv then downloads the Python interpreter if it is not available.
+# for more on this feature read the [uv python documentation](https://docs.astral.sh/uv/concepts/python-versions/)
+# Default: python3
+PRIMARY_PYTHON?=3.13
+
+# Minimum required Python version.
+# Default: 3.10
+PYTHON_MIN_VERSION?=3.13
+
+# Install packages using the given package installer method.
+# Supported are `pip` and `uv`. When `uv` is selected, a global installation
+# is auto-detected and used if available. Otherwise, uv is installed in the
+# virtual environment or using `PRIMARY_PYTHON`, depending on the
+# `VENV_ENABLED` setting.
+# Default: pip
+PYTHON_PACKAGE_INSTALLER?=uv
+
+# Python version for UV to install/use when creating virtual
+# environments with global UV. Passed to `uv venv -p VALUE`. Supports version
+# specs like `3.11`, `3.14`, `cpython@3.14`. Defaults to PRIMARY_PYTHON value
+# for backward compatibility.
+# Default: $(PRIMARY_PYTHON)
+UV_PYTHON?=$(PRIMARY_PYTHON)
+
+# Flag whether to use virtual environment. If `false`, the
+# interpreter according to `PRIMARY_PYTHON` found in `PATH` is used.
+# Default: true
+VENV_ENABLED?=true
+
+# Flag whether to create a virtual environment. If set to `false`
+# and `VENV_ENABLED` is `true`, `VENV_FOLDER` is expected to point to an
+# existing virtual environment.
+# Default: true
+VENV_CREATE?=true
+
+# The folder of the virtual environment.
+# If `VENV_ENABLED` is `true` and `VENV_CREATE` is true it is used as the
+# target folder for the virtual environment. If `VENV_ENABLED` is `true` and
+# `VENV_CREATE` is false it is expected to point to an existing virtual
+# environment. If `VENV_ENABLED` is `false` it is ignored.
+# Default: .venv
+VENV_FOLDER?=.venv
+
+# mxdev to install in virtual environment.
+# Default: mxdev
+MXDEV?=mxdev
+
+# mxmake to install in virtual environment.
+# Default: mxmake
+MXMAKE?=mxmake
+
+## docs.sphinx
+
+# Documentation source folder.
+# Default: docs/source
+DOCS_SOURCE_FOLDER?=sources
+
+# Documentation generation target folder.
+# Default: docs/html
+DOCS_TARGET_FOLDER?=html
+
+# Documentation linkcheck output folder.
+# Default: docs/linkcheck
+DOCS_LINKCHECK_FOLDER?=docs/linkcheck
+
+# Documentation Python requirements to be installed (via pip).
+# No default value.
+DOCS_REQUIREMENTS?=myst_parser sphinxcontrib.mermaid shibuya sphinx-design sphinx-copybutton
+
+##############################################################################
+# END SETTINGS - DO NOT EDIT BELOW THIS LINE
+##############################################################################
+
+INSTALL_TARGETS?=
+DIRTY_TARGETS?=
+CLEAN_TARGETS?=
+PURGE_TARGETS?=
+
+export PATH:=$(if $(EXTRA_PATH),$(EXTRA_PATH):,)$(PATH)
+
+# Helper variable: adds trailing slash to PROJECT_PATH_PYTHON only if non-empty
+PYTHON_PROJECT_PREFIX=$(if $(PROJECT_PATH_PYTHON),$(PROJECT_PATH_PYTHON)/,)
+
+# Defensive settings for make: https://tech.davis-hansson.com/p/make/
+SHELL:=bash
+.ONESHELL:
+# for Makefile debugging purposes add -x to the .SHELLFLAGS
+.SHELLFLAGS:=-eu -o pipefail -O inherit_errexit -c
+.SILENT:
+.DELETE_ON_ERROR:
+MAKEFLAGS+=--warn-undefined-variables
+MAKEFLAGS+=--no-builtin-rules
+
+# mxmake folder
+MXMAKE_FOLDER?=.mxmake
+
+# Sentinel files
+SENTINEL_FOLDER?=$(MXMAKE_FOLDER)/sentinels
+SENTINEL?=$(SENTINEL_FOLDER)/about.txt
+$(SENTINEL): $(firstword $(MAKEFILE_LIST))
+	@mkdir -p $(SENTINEL_FOLDER)
+	@echo "Sentinels for the Makefile process." > $(SENTINEL)
+
+##############################################################################
+# mxenv
+##############################################################################
+
+OS?=
+
+# Determine the executable path
+ifeq ("$(VENV_ENABLED)", "true")
+export VIRTUAL_ENV=$(abspath $(VENV_FOLDER))
+ifeq ("$(OS)", "Windows_NT")
+VENV_EXECUTABLE_FOLDER=$(VIRTUAL_ENV)/Scripts
+else
+VENV_EXECUTABLE_FOLDER=$(VIRTUAL_ENV)/bin
+endif
+export PATH:=$(VENV_EXECUTABLE_FOLDER):$(PATH)
+MXENV_PYTHON=python
+else
+MXENV_PYTHON=$(PRIMARY_PYTHON)
+endif
+
+# Determine the package installer with non-interactive flags
+ifeq ("$(PYTHON_PACKAGE_INSTALLER)","uv")
+PYTHON_PACKAGE_COMMAND=uv pip --no-progress
+else
+PYTHON_PACKAGE_COMMAND=$(MXENV_PYTHON) -m pip
+endif
+
+# Auto-detect global uv availability (simple existence check)
+ifeq ("$(PYTHON_PACKAGE_INSTALLER)","uv")
+UV_AVAILABLE:=$(shell command -v uv >/dev/null 2>&1 && echo "true" || echo "false")
+else
+UV_AVAILABLE:=false
+endif
+
+# Determine installation strategy
+# depending on the PYTHON_PACKAGE_INSTALLER and UV_AVAILABLE
+# - both vars can be false or
+# - one of them can be true,
+# - but never boths.
+USE_GLOBAL_UV:=$(shell [[ "$(PYTHON_PACKAGE_INSTALLER)" == "uv" && "$(UV_AVAILABLE)" == "true" ]] && echo "true" || echo "false")
+USE_LOCAL_UV:=$(shell [[ "$(PYTHON_PACKAGE_INSTALLER)" == "uv" && "$(UV_AVAILABLE)" == "false" ]] && echo "true" || echo "false")
+
+# Check if global UV is outdated (non-blocking warning)
+ifeq ("$(USE_GLOBAL_UV)","true")
+UV_OUTDATED:=$(shell uv self update --dry-run 2>&1 | grep -q "Would update" && echo "true" || echo "false")
+else
+UV_OUTDATED:=false
+endif
+
+MXENV_TARGET:=$(SENTINEL_FOLDER)/mxenv.sentinel
+$(MXENV_TARGET): $(SENTINEL)
+	# Validation: Check Python version if not using global uv
+ifneq ("$(USE_GLOBAL_UV)","true")
+	@$(PRIMARY_PYTHON) -c "import sys; vi = sys.version_info; sys.exit(1 if (int(vi[0]), int(vi[1])) >= tuple(map(int, '$(PYTHON_MIN_VERSION)'.split('.'))) else 0)" \
+		&& echo "Need Python >= $(PYTHON_MIN_VERSION)" && exit 1 || :
+else
+	@echo "Using global uv for Python $(UV_PYTHON)"
+endif
+	# Validation: Check VENV_FOLDER is set if venv enabled
+	@[[ "$(VENV_ENABLED)" == "true" && "$(VENV_FOLDER)" == "" ]] \
+		&& echo "VENV_FOLDER must be configured if VENV_ENABLED is true" && exit 1 || :
+	# Validation: Check uv not used with system Python
+	@[[ "$(VENV_ENABLED)" == "false" && "$(PYTHON_PACKAGE_INSTALLER)" == "uv" ]] \
+		&& echo "Package installer uv does not work with a global Python interpreter." && exit 1 || :
+	# Warning: Notify if global UV is outdated
+ifeq ("$(UV_OUTDATED)","true")
+	@echo "WARNING: A newer version of uv is available. Run 'uv self update' to upgrade."
+endif
+
+	# Create virtual environment
+ifeq ("$(VENV_ENABLED)", "true")
+ifeq ("$(VENV_CREATE)", "true")
+ifeq ("$(USE_GLOBAL_UV)","true")
+	@echo "Setup Python Virtual Environment using global uv at '$(VENV_FOLDER)'"
+	@uv venv --allow-existing --no-progress -p $(UV_PYTHON) --seed $(VENV_FOLDER)
+else
+	@echo "Setup Python Virtual Environment using module 'venv' at '$(VENV_FOLDER)'"
+	@$(PRIMARY_PYTHON) -m venv $(VENV_FOLDER)
+	@$(MXENV_PYTHON) -m ensurepip -U
+endif
+endif
+else
+	@echo "Using system Python interpreter"
+endif
+
+	# Install uv locally if needed
+ifeq ("$(USE_LOCAL_UV)","true")
+	@echo "Install uv in virtual environment"
+	@$(MXENV_PYTHON) -m pip install uv
+endif
+
+	# Install/upgrade core packages
+	@$(PYTHON_PACKAGE_COMMAND) install -U pip setuptools wheel
+	@echo "Install/Update MXStack Python packages"
+	@$(PYTHON_PACKAGE_COMMAND) install -U $(MXDEV) $(MXMAKE)
+	@touch $(MXENV_TARGET)
+
+.PHONY: mxenv
+mxenv: $(MXENV_TARGET)
+
+.PHONY: mxenv-dirty
+mxenv-dirty:
+	@rm -f $(MXENV_TARGET)
+
+.PHONY: mxenv-clean
+mxenv-clean: mxenv-dirty
+ifeq ("$(VENV_ENABLED)", "true")
+ifeq ("$(VENV_CREATE)", "true")
+	@rm -rf $(VENV_FOLDER)
+endif
+else
+	@$(PYTHON_PACKAGE_COMMAND) uninstall -y $(MXDEV)
+	@$(PYTHON_PACKAGE_COMMAND) uninstall -y $(MXMAKE)
+endif
+
+INSTALL_TARGETS+=mxenv
+DIRTY_TARGETS+=mxenv-dirty
+CLEAN_TARGETS+=mxenv-clean
+
+##############################################################################
+# sphinx
+##############################################################################
+
+# additional targets required for building docs.
+DOCS_TARGETS+=
+
+SPHINX_BIN=sphinx-build
+SPHINX_AUTOBUILD_BIN=sphinx-autobuild
+
+DOCS_TARGET:=$(SENTINEL_FOLDER)/sphinx.sentinel
+$(DOCS_TARGET): $(MXENV_TARGET)
+	@echo "Install Sphinx"
+	@$(PYTHON_PACKAGE_COMMAND) install -U sphinx sphinx-autobuild $(DOCS_REQUIREMENTS)
+	@touch $(DOCS_TARGET)
+
+.PHONY: docs
+docs: $(DOCS_TARGET) $(DOCS_TARGETS)
+	@echo "Build sphinx docs"
+	@$(SPHINX_BIN) $(DOCS_SOURCE_FOLDER) $(DOCS_TARGET_FOLDER)
+
+.PHONY: docs-live
+docs-live: $(DOCS_TARGET) $(DOCS_TARGETS)
+	@echo "Rebuild Sphinx documentation on changes, with live-reload in the browser"
+	@$(SPHINX_AUTOBUILD_BIN) $(DOCS_SOURCE_FOLDER) $(DOCS_TARGET_FOLDER)
+
+.PHONY: docs-linkcheck
+docs-linkcheck: $(DOCS_TARGET) $(DOCS_TARGETS)
+	@echo "Run Sphinx linkcheck"
+	@$(SPHINX_BIN) -b linkcheck $(DOCS_SOURCE_FOLDER) $(DOCS_LINKCHECK_FOLDER)
+
+.PHONY: docs-dirty
+docs-dirty:
+	@rm -f $(DOCS_TARGET)
+
+.PHONY: docs-clean
+docs-clean: docs-dirty
+	@test -e $(MXENV_PYTHON) && $(MXENV_PYTHON) -m pip uninstall -y \
+		sphinx sphinx-autobuild $(DOCS_REQUIREMENTS) || :
+	@rm -rf $(DOCS_TARGET_FOLDER)
+
+INSTALL_TARGETS+=$(DOCS_TARGET)
+DIRTY_TARGETS+=docs-dirty
+CLEAN_TARGETS+=docs-clean
+
+##############################################################################
+# Custom includes
+##############################################################################
+
+-include $(INCLUDE_MAKEFILE)
+
+##############################################################################
+# Default targets
+##############################################################################
+
+INSTALL_TARGET:=$(SENTINEL_FOLDER)/install.sentinel
+$(INSTALL_TARGET): $(INSTALL_TARGETS)
+	@touch $(INSTALL_TARGET)
+
+.PHONY: install
+install: $(INSTALL_TARGET)
+	@touch $(INSTALL_TARGET)
+
+.PHONY: run
+run: $(RUN_TARGET)
+
+.PHONY: deploy
+deploy: $(DEPLOY_TARGETS)
+
+.PHONY: dirty
+dirty: $(DIRTY_TARGETS)
+	@rm -f $(INSTALL_TARGET)
+
+.PHONY: clean
+clean: dirty $(CLEAN_TARGETS)
+	@rm -rf $(CLEAN_TARGETS) $(MXMAKE_FOLDER) $(CLEAN_FS)
+
+.PHONY: purge
+purge: clean $(PURGE_TARGETS)
+
+.PHONY: runtime-clean
+runtime-clean:
+	@echo "Remove runtime artifacts, like byte-code and caches."
+	@find . -name '*.py[c|o]' -delete
+	@find . -name '*~' -exec rm -f {} +
+	@find . -name '__pycache__' -exec rm -fr {} +
+

package/documentation/README.md

@@ -0,0 +1,284 @@
+# cdk8s-plone Documentation
+
+This directory contains the complete documentation for cdk8s-plone, built using [Sphinx](https://www.sphinx-doc.org/) with [MyST Parser](https://myst-parser.readthedocs.io/) and following the [Diátaxis framework](https://diataxis.fr/).
+
+## 📚 View Documentation
+
+**Published documentation:** https://bluedynamics.github.io/cdk8s-plone/
+
+## 🏗️ Building Documentation Locally
+
+### Prerequisites
+
+- Python 3.13+ (or Python 3.9+ with manual configuration)
+- `make` command
+- `uv` (fast Python package installer) - optional but recommended
+
+### Quick Start
+
+```bash
+# Navigate to documentation directory
+cd documentation
+
+# Build HTML documentation
+make docs
+
+# Open in browser
+open html/index.html  # macOS
+xdg-open html/index.html  # Linux
+```
+
+The first build will:
+1. Create a Python virtual environment (.venv)
+2. Install Sphinx and required extensions
+3. Generate HTML documentation
+
+Subsequent builds will reuse the virtual environment and be much faster.
+
+### Development with Live Reload
+
+For documentation writing, use the live-reload server:
+
+```bash
+cd documentation
+make docs-live
+```
+
+This starts a development server at http://localhost:8000 that automatically rebuilds and refreshes when you save changes.
+
+### Clean Build
+
+To remove generated files and rebuild from scratch:
+
+```bash
+make clean
+make docs
+```
+
+## 📝 Documentation Structure
+
+The documentation follows the [Diátaxis framework](https://diataxis.fr/), organizing content into four categories:
+
+```
+sources/
+├── index.md                  # Main landing page
+├── tutorials/                # Learning-oriented (step-by-step lessons)
+│   └── index.md
+├── how-to/                   # Goal-oriented (solve specific problems)
+│   └── index.md
+├── reference/                # Information-oriented (technical specs)
+│   ├── index.md
+│   └── api/                  # API documentation
+├── explanation/              # Understanding-oriented (concepts)
+│   └── index.md
+└── _static/                  # Static assets (CSS, images, fonts)
+    ├── brand-theme.css       # Cyberpunk theme styling
+    ├── custom-icons.css      # Icon styling
+    ├── logo-fix.js           # Logo link fixes
+    ├── plone-logo.svg        # Project logo (placeholder)
+    ├── kup6s-icon-*.svg      # Category icons
+    └── fonts/                # Web fonts (Rajdhani, Orbitron, Hack)
+```
+
+### Content Guidelines
+
+#### Tutorials (Learning-Oriented)
+- Step-by-step lessons for building skills
+- Complete, reproducible examples
+- Learning goals clearly stated
+- Assumes beginner knowledge
+
+#### How-To Guides (Goal-Oriented)
+- Solutions to specific problems
+- Assumes some knowledge
+- Focus on accomplishing a task
+- Recipe-style format
+
+#### Reference (Information-Oriented)
+- Technical specifications
+- API documentation
+- Configuration options
+- Dry, factual descriptions
+
+#### Explanation (Understanding-Oriented)
+- Conceptual discussion
+- Architecture and design decisions
+- The "why" behind choices
+- Broaden understanding
+
+## 🎨 Theme and Styling
+
+The documentation uses:
+- **Theme:** [Shibuya](https://shibuya.lepture.com/) - Modern, responsive Sphinx theme
+- **Parser:** [MyST](https://myst-parser.readthedocs.io/) - Markdown with extensions
+- **Style:** Cyberpunk-inspired (cyan #00d4ff, dark background)
+- **Fonts:**
+  - Rajdhani (headings) - geometric, futuristic
+  - Hack (body/code) - monospace, highly legible
+  - Orbitron (special emphasis) - geometric, bold
+
+## 🔧 Configuration
+
+Key configuration files:
+
+- **`Makefile`** - Build automation (generated by mxmake)
+- **`mx.ini`** - mxmake settings
+- **`sources/conf.py`** - Sphinx configuration
+- **`.gitignore`** - Excludes build artifacts
+
+### Sphinx Extensions
+
+- `myst_parser` - Markdown support
+- `sphinxcontrib.mermaid` - Diagram support (```mermaid)
+- `sphinx_design` - Grid and card directives
+- `sphinx_copybutton` - Copy button for code blocks
+
+### MyST Extensions
+
+- `deflist` - Definition lists
+- `colon_fence` - ::: directive syntax for grids/cards
+- Mermaid fence as directive
+
+## 📖 Writing Documentation
+
+### Markdown Format
+
+All documentation is written in Markdown with MyST extensions.
+
+**Example:**
+
+```markdown
+# Page Title
+
+## Section
+
+Regular Markdown content with **bold**, *italic*, and `code`.
+
+### Code Blocks
+
+\```python
+import example
+print("Hello, world!")
+\```
+
+### Grid Cards (Diátaxis Landing Pages)
+
+::::{grid} 2
+:gutter: 3
+
+:::{grid-item-card} Card Title
+:img-top: _static/icon.svg
+:link: path/to/page
+:link-type: doc
+
+Card description
+:::
+
+::::
+```
+
+### Internal Links
+
+```markdown
+[Link text](path/to/file.md)
+[Link to section](file.md#section-heading)
+```
+
+### Images
+
+```markdown
+![Alt text](path/to/image.png)
+
+# Or with MyST directive:
+\```{image} path/to/image.png
+:width: 200px
+:align: center
+\```
+```
+
+### Tables
+
+```markdown
+| Column 1 | Column 2 |
+|----------|----------|
+| Value 1  | Value 2  |
+```
+
+### Diagrams
+
+Use Mermaid for diagrams:
+
+````markdown
+```mermaid
+graph LR
+    A[Start] --> B[Process]
+    B --> C[End]
+```
+````
+
+## 🚀 Deployment
+
+Documentation will be automatically deployed to GitHub Pages via GitHub Actions:
+
+1. **Trigger:** Push to `main` branch or manual workflow dispatch
+2. **Build:** Ubuntu runner builds documentation with Sphinx
+3. **Deploy:** Artifacts uploaded to GitHub Pages
+4. **URL:** https://bluedynamics.github.io/cdk8s-plone/
+
+## 📦 Dependencies
+
+Documentation dependencies (installed automatically by `make docs`):
+
+- sphinx - Documentation generator
+- sphinx-autobuild - Live-reload server
+- myst_parser - Markdown parser
+- sphinxcontrib.mermaid - Mermaid diagram support
+- shibuya - Sphinx theme
+- sphinx-design - Grid/card directives
+- sphinx-copybutton - Code block copy button
+
+## 🤝 Contributing
+
+When contributing to documentation:
+
+1. **Follow Diátaxis categories** - Put content in the right section
+2. **Use clear headings** - H1 for page title, H2 for sections
+3. **Test locally** - Always build and preview before committing
+4. **Check links** - Ensure all internal links work
+5. **Use consistent style** - Follow existing formatting patterns
+6. **Add images to _static/** - Keep static assets organized
+
+## 🔍 Troubleshooting
+
+### Build Errors
+
+**Error: `sphinx-build: command not found`**
+- Solution: Run `make clean` then `make docs` to reinstall dependencies
+
+**Error: Unknown directive type "grid"**
+- Solution: Ensure `sphinx_design` is installed: `pip install sphinx-design`
+
+**Error: "Cannot find reference" warnings**
+- Solution: Check that linked files exist and paths are correct
+
+### Theme Issues
+
+**Fonts not loading**
+- Check that font files exist in `_static/fonts/`
+- Verify paths in `brand-theme.css`
+
+**Logo not displaying**
+- Ensure `_static/plone-logo.svg` exists
+- Check `html_logo` setting in `conf.py`
+
+## 📚 Resources
+
+- [Diátaxis Framework](https://diataxis.fr/) - Documentation organization philosophy
+- [MyST Parser Documentation](https://myst-parser.readthedocs.io/) - Markdown syntax reference
+- [Sphinx Documentation](https://www.sphinx-doc.org/) - Sphinx features and configuration
+- [Shibuya Theme](https://shibuya.lepture.com/) - Theme documentation
+- [Mermaid Diagrams](https://mermaid.js.org/) - Diagram syntax
+
+---
+
+**Questions?** Open an issue on GitHub or ask in the project discussions.

package/documentation/mx.ini

@@ -0,0 +1,3 @@
+[settings]
+threads = 5
+version-overrides =