Merge pull request #25 from codesyntax/docs

Docs

Author: erral

.github/workflows/docs.yml

@@ -0,0 +1,55 @@
+name: "Publish Documentation"
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: "Build Docs"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "docs/uv.lock"
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: "Deploy to GitHub Pages"
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

AGENTS.md

@@ -12,11 +12,13 @@ This project uses `make` as the primary task runner, backed by `uv` for Python e
   make install
   ```
   *(Always recommend `make install` to users. It handles all dependencies, `uv venv`, and setup. NEVER recommend using `pip install` or `uv pip` directly.)*
+- **Sync dependencies**: `make sync`
 - **Start the Plone instance**:
   ```bash
   make start
   ```
 - **Clean the environment** (without removing data): `make clean`
+- **Remove all content**: `make remove-data`
 - **Create a new site**: `make create-site`
 
 ### Linting and Formatting
@@ -34,11 +36,11 @@ Tests are written using `pytest` and `plone.app.testing`.
 - **Run tests with coverage**: `make test-coverage`
 - **Run a single test file**: 
   ```bash
-  ./.venv/bin/pytest src/cs_dynamicpages/tests/test_ct_dynamic_page_folder.py
+  ./.venv/bin/pytest src/cs_dynamicpages/tests/test_file.py
   ```
 - **Run a specific test method/class**:
   ```bash
-  ./.venv/bin/pytest src/cs_dynamicpages/tests/test_ct_dynamic_page_folder.py::DynamicPageFolderIntegrationTest::test_ct_dynamic_page_folder_adding
+  ./.venv/bin/pytest src/cs_dynamicpages/tests/test_file.py::TestClass::test_method
   ```
 
 ---
@@ -49,24 +51,23 @@ Tests are written using `pytest` and `plone.app.testing`.
 - **Line Length**: 88 characters (configured in `pyproject.toml`).
 - **Python Version**: Target Python 3.10 (`>=3.10,<3.14`).
 - **Imports**: Formatted using `ruff`'s `isort` rules.
-  - Case-insensitive sorting.
-  - Force single-line imports (`from X import Y` on separate lines for each `Y`).
+  - Case-insensitive sorting, force single-line imports (`from X import Y` on separate lines).
   - No sections (all imports sorted alphabetically regardless of third-party/stdlib).
   - 2 blank lines after imports, 1 blank line between types.
-- **Exceptions**: Ignore `E731` (DoNotAssignLambda). Use `# noqa` only when absolutely necessary and document why.
+- **Exceptions**: Ignore `E731` (DoNotAssignLambda). Use `# noqa` only when necessary.
 
 ### Naming Conventions
 - **Classes**: `PascalCase` (e.g., `DynamicPageFolder`).
 - **Interfaces**: Prefix with `I` and use `PascalCase` (e.g., `IDynamicPageFolder`).
 - **Methods, Variables, and Functions**: `snake_case` (e.g., `dynamic_page_folder_id`).
 - **Constants**: `UPPER_SNAKE_CASE` (e.g., `TEST_USER_ID`).
-- **Filenames**: `snake_case` for Python and XML files (except specific Zope configurations like `configure.zcml` or specific profiles like `Plone_Site.xml` which follow Plone's exact casing).
+- **Filenames**: `snake_case` for Python and XML files (except `configure.zcml` / Plone profiles).
 
 ### Types & Schema
 - Define Dexterity schemas using `plone.supermodel.model.Schema`.
 - Apply `@implementer(IYourInterface)` to your content type classes.
 - Explicitly subclass `Container` or `Item` from `plone.dexterity.content`.
-- Avoid unnecessary types annotations if Zope schemas already enforce types (`zope.schema`).
+- Avoid unnecessary type annotations if Zope schemas already enforce types (`zope.schema`).
 
 ### Error Handling
 - Use standard Python exceptions or `plone.api.exc` (like `InvalidParameterError`) when using `plone.api`.
@@ -75,7 +76,7 @@ Tests are written using `pytest` and `plone.app.testing`.
 
 ### XML, ZCML, and PT
 - **XML/ZCML**: Keep it strictly formatted with `zpretty`. Indent with 2 spaces. 
-- **Page Templates (PT)**: Ensure they are properly formed HTML/XML. Keep logic in the python views, not in the templates.
+- **Page Templates (PT)**: Ensure they are properly formed HTML/XML. Keep logic in python views, not templates.
 
 ---
 
@@ -91,8 +92,7 @@ These rules are strictly enforced for AI agents interacting with this Plone repo
    - If no docs are found, EXPLICITLY STATE: "I cannot find official documentation for this." Trial and error MUST be labeled: "This requires trial and error - not documented."
 
 2. **Terminal Commands**
-   - Provide ONE step at a time.
-   - WAIT for confirmation before moving to the next step.
+   - Provide ONE step at a time. WAIT for confirmation before moving to the next step.
    - Include the full command with all parameters.
    - ALWAYS recommend using `make` commands (`make install`, `make start`). NEVER recommend `pip install`, `uv add` or `uv pip` directly.
 
@@ -109,8 +109,7 @@ These rules are strictly enforced for AI agents interacting with this Plone repo
    - In README, review the code if necessary to explain features correctly (e.g. use `- Register a behavior providing additional fields representing contact information` instead of just `- Behavior`).
 
 5. **Internationalization (i18n)**
-   - All UI strings MUST be translatable.
-   - Use `cs_dynamicpages` as the i18n domain.
+   - All UI strings MUST be translatable. Use `cs_dynamicpages` as the i18n domain.
    - Example: `_(u"My string")` imported from the project's MessageFactory.
    - Run `make i18n` to update `.pot` and `.po` files.
 
@@ -125,5 +124,26 @@ These rules are strictly enforced for AI agents interacting with this Plone repo
    - Acknowledge good ideas and creative solutions.
 
 8. **Definition of Success**
-   - Success is ONLY a fully functional, tested result.
-   - Never claim success for partial or broken implementations.
+   - Success is ONLY a fully functional, tested result. Never claim success for partial or broken implementations.
+
+---
+
+## 4. Engram Persistent Memory — Protocol
+
+You have access to Engram, a persistent memory system that survives across sessions and compactions.
+
+### WHEN TO SAVE (mandatory — not optional)
+Call `mem_save` IMMEDIATELY after any of these:
+- Bug fix completed
+- Architecture or design decision made
+- Non-obvious discovery about the codebase
+- Configuration change or environment setup
+- Pattern established (naming, structure, convention)
+- User preference or constraint learned
+
+### WHEN TO SEARCH MEMORY
+- Call `mem_context` — checks recent session history (fast, cheap)
+- If not found, call `mem_search` with relevant keywords (FTS5 full-text search)
+
+### SESSION CLOSE PROTOCOL (mandatory)
+Before ending a session, you MUST call `mem_session_summary` using the structured outline (Goal, Instructions, Discoveries, Accomplished, Next Steps, Relevant Files). This is NOT optional.

docs/.gitignore

@@ -0,0 +1,7 @@
+# Python related
+*.egg-info
+.venv
+
+# Documentation builds
+_build
+styles/Microsoft

docs/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.13"
+  commands:
+    # Cancel building pull requests when there aren't changes in the docs directory or YAML file.
+    # You can add any other files or directories that you'd like here as well,
+    # like your docs requirements file, or other files that will change your docs build.
+    #
+    # If there are no changes (git diff exits with 0) we force the command to return with 183.
+    # This is a special exit code on Read the Docs that will cancel the build immediately.
+    - |
+      if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/docs/ docs/styles/ .readthedocs.yaml docs/.vale.ini docs/Makefile docs/uv.lock .github/workflows/docs.yml;
+      then
+        exit 183;
+      fi
+    - cd docs && make rtd-pr-preview

docs/.vale.ini

@@ -0,0 +1,12 @@
+StylesPath = styles
+
+MinAlertLevel = suggestion
+
+Vocab = Base,Plone
+
+Packages = Microsoft
+
+[*]
+BasedOnStyles = Vale, Microsoft
+Microsoft.Contractions = suggestion
+Microsoft.Units = suggestion

docs/LICENSE.md

@@ -0,0 +1,3 @@
+cs_dynamicpages Copyright 2026, CodeSyntax
+
+The text and illustrations in this website are licensed by the Plone Foundation under a [Creative Commons Attribution 4.0 International](https://creativecommons.org/licenses/by/4.0/) license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see [https://plone.org/foundation/logo](https://plone.org/foundation/logo). All other trademarks are owned by their respective owners.

docs/Makefile

@@ -0,0 +1,138 @@
+# Makefile for Sphinx documentation
+.DEFAULT_GOAL   = help
+SHELL           = bash
+
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+PAPER           ?=
+
+# Internal variables.
+GREEN=`tput setaf 2`
+RESET=`tput sgr0`
+SPHINXBUILD     = "$(realpath .venv/bin/sphinx-build)"
+DOCS_DIR        = ./docs/
+BUILDDIR        = ./_build
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(DOCS_DIR)
+VALEFILES       := $(shell find $(DOCS_DIR) -type f -name "*.md" -print)
+VALEOPTS        ?=
+PYTHONVERSION   = >=3.11,<3.14
+
+# Add the following 'help' target to your Makefile
+# And add help text after each target name starting with '\#\#'
+.PHONY: help
+help:  # This help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+
+# environment management
+.venv/bin/python:  ## Create Python virtual environment and install package requirements
+	@uv sync
+
+.PHONY: install
+install:  .venv/bin/python ## Sync package requirements
+
+
+.PHONY: init
+init: clean clean-python .venv/bin/python  ## Clean docs build directory and Python, and initialize Python virtual environment
+
+.PHONY: clean
+clean:  ## Clean docs build directory
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+
+.PHONY: clean-python
+clean-python: clean
+	rm -rf .venv/
+	rm -rf *.egg-info
+# /environment management
+
+
+# documentation builders
+.PHONY: html
+html: .venv/bin/python  ## Build html
+	@uv run sphinx-build -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: livehtml
+livehtml: .venv/bin/python  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	@uv run sphinx-autobuild \
+		--ignore "*.swp" \
+		--port 8050 \
+		-b html $(DOCS_DIR) "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
+
+.PHONY: dirhtml
+dirhtml: .venv/bin/python
+	@uv run sphinx-build -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml: .venv/bin/python
+	@uv run sphinx-build -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: text
+text: .venv/bin/python
+	@uv run sphinx-build -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: changes
+changes: .venv/bin/python
+	@uv run sphinx-build -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: rtd-prepare
+rtd-prepare:  ## Prepare environment on Read the Docs
+	asdf plugin add uv
+	asdf install uv latest
+	asdf global uv latest
+
+.PHONY: rtd-pr-preview  ## Build pull request previews on Read the Docs
+rtd-pr-preview: rtd-prepare .venv/bin/python ## Build pull request preview on Read the Docs
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
+
+.PHONY: build
+build: html  ## Build documentation in HTML format
+
+# /documentation builders
+
+
+# test
+.PHONY: linkcheck
+linkcheck: .venv/bin/python  ## Run linkcheck
+	@uv run sphinx-build -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: linkcheckbroken
+linkcheckbroken: .venv/bin/python  ## Run linkcheck and show only broken links
+	@uv run sphinx-build -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck | GREP_COLORS='0;31' grep -wi "broken\|redirect" --color=always | GREP_COLORS='0;31' grep -vi "https://github.com/plone/volto/issues/" --color=always && if test $$? = 0; then exit 1; fi || test $$? = 1
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: doctest
+doctest: .venv/bin/python  ## Test snippets in the documentation
+	@uv run sphinx-build -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: vale
+vale: .venv/bin/python  ## Run Vale style, grammar, and spell checks
+	@uv run vale sync
+	@uv run vale --no-wrap $(VALEOPTS) $(VALEFILES)
+	@echo "Vale is finished; look for any errors in the above output."
+	@echo
+
+.PHONY: test
+test: clean vale linkcheckbroken doctest  ## Clean docs build, then run vale, linkcheckbroken, and doctest
+
+.PHONY: all
+all: clean vale linkcheckbroken html  ## Clean docs build, then run linkcheckbroken, and build html
+# /test