lint and format

Author: libargutxi

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 2025, Lur Ibargutxi
+
+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,133 @@
+# 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`
+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
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
+# /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

docs/README.md

@@ -0,0 +1,124 @@
+# cs_dynamicpages
+
+Documentation for cs_dynamicpages.
+An addon to create dynamic pages for Plone
+
+This project provides a Sphinx-based documentation environment for your Plone project, powered by the [Plone Sphinx Theme](https://github.com/plone/plone-sphinx-theme).
+It's generated using the `documentation_starter` template from [Cookieplone](https://github.com/plone/cookieplone).
+
+
+## Prerequisites
+
+-   [uv](https://docs.astral.sh/uv/) is the recommended tool for managing Python versions and project dependencies.
+
+To install uv, use the following command, or visit the [uv installation page](https://docs.astral.sh/uv/getting-started/installation/) for alternative methods.
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+
+## Build documentation
+
+To build the HTML documentation, issue the following command.
+
+```shell
+make html
+```
+
+To build the HTML documentation and view a live preview while editing your documentation, issue the following command.
+
+```shell
+make livehtml
+```
+
+To check for broken links in your documentation, issue the following command.
+
+```shell
+make linkcheckbroken
+```
+
+To check spelling, grammar, and style in your documentation, issue the following command.
+You should pay attention to errors and warnings, and suggestions may get noisy.
+
+```shell
+make vale
+```
+
+To delete the `docs` build directory and Python virtual environment, and reinitialize Python virtual environment, issue the following command.
+This is useful to force reinstall dependencies and purge cached files in Sphinx builds.
+
+```shell
+make init
+```
+
+For more `make` commands, issue the following command.
+
+```shell
+make help
+```
+
+
+## Customize the cs_dynamicpages documentation
+
+This section provides how-to guidance to customize your documentation.
+
+The file `docs/conf.py` controls the configuration of your documentation.
+It has extensive comments for each part, often with links to the authoritative documentation for extensions and configuration.
+
+The following sections describe customization not addressed in `docs/conf.py`.
+
+
+### Manage dependencies
+
+You can configure which dependencies or requirements you want to use in your documentation using uv.
+Requirements are stored in the `dev` dependency group in the `pyproject.toml` file.
+
+To add a requirement, use the following command.
+
+```shell
+uv add --dev my-requirement
+```
+
+To remove a requirement, use the following command.
+
+```shell
+uv remove --dev my-requirement
+```
+
+See also uv's documentation [Development dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/#development-dependencies).
+
+After installing a dependency, you might need to add it to your documentation's configuration file, `conf.py`, under the `extensions` key.
+
+
+### Replace static files
+
+You might want to replace the default static files, located in `docs/_static`, `logo.svg` and `favicon.ico`.
+Plone Sphinx Theme is configured to use these files when rendering documentation to HTML.
+
+If you rename `logo.svg`, you must update `conf.py`, under the `html_logo`, `ogp_image`, and `latex_logo` keys.
+
+
+## Read the Docs
+
+Now that you've built your documentation, how do you publish it?
+And how do you get collaborators to easily review your changes to your documentation?
+
+Thankfully, [Read the Docs](https://about.readthedocs.com/) provides both hosting of documentation and pull request previews.
+For public repositories, this service is free.
+However, the Plone Foundation donates to Read the Docs for their unwavering support to open source software, and encourages you to do the same.
+
+Your documentation scaffold is partially configured to use Read the Docs.
+In several files, search for the string `MY_READTHEDOCS_PROJECT_SLUG`.
+You'll need to replace that string with the slug that Read the Docs creates for you when you import your project.
+
+For complete documentation of this process, see the Plone 6 Documentation [Pull request preview builds](https://6.docs.plone.org/contributing/documentation/admins.html#pull-request-preview-builds).
+
+See also Read the Docs documentation:
+
+-   [Pull request previews](https://docs.readthedocs.com/platform/stable/pull-requests.html)
+-   [Build process overview](https://docs.readthedocs.com/platform/stable/builds.html)
+
+## Credits and acknowledgements 🙏
+
+This was generated by the [cookieplone-templates documentation_starter template](https://github.com/plone/cookieplone-templates/tree/main/documentation_starter) on 2025-07-07 07:27:42. A special thanks to all contributors and supporters!