Merge pull request #26 from codesyntax/llms-docs

erral · web-flow · commit a7302afa070d · 2026-03-25T14:14:32.000+01:00
Llms docs
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -14,10 +14,57 @@ jobs:
     name: "Backend: Lint"
     needs:
       - config
-    uses: plone/meta/.github/workflows/backend-lint.yml@2.x
-    with:
-      python-version: ${{ needs.config.outputs.python-version }}
-      plone-version: ${{ needs.config.outputs.plone-version }}
+    runs-on: ubuntu-latest
+    env:
+      PYTHON_VERSION: ${{ needs.config.outputs.python-version }}
+      PLONE_VERSION: ${{ needs.config.outputs.plone-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup codebase
+        uses: plone/meta/.github/actions/setup_backend_uv@2.x
+        with:
+          python-version: ${{ needs.config.outputs.python-version }}
+          plone-version: ${{ needs.config.outputs.plone-version }}
+
+      - name: Check formatting
+        id: ruff-format
+        shell: bash
+        run: |
+          uvx ruff@latest format --diff
+
+      - name: Check lint
+        id: ruff-lint
+        if: ${{ success() || failure() }}
+        shell: bash
+        run: |
+          uvx ruff@latest check --diff
+
+      - name: Check XML / ZCML
+        id: zpretty
+        if: ${{ success() || failure() }}
+        shell: bash
+        run: |
+          uvx zpretty@latest --check src
+
+      - name: Check Python Versions
+        id: py-versions
+        if: ${{ success() || failure() }}
+        shell: bash
+        run: |
+          uvx check-python-versions@latest .
+
+      - name: Report
+        if: ${{ success() || failure() }}
+        run: |
+          echo '# Code Analysis' >> $GITHUB_STEP_SUMMARY
+          echo '| Test | Status |' >> $GITHUB_STEP_SUMMARY
+          echo '| --- | --- |' >> $GITHUB_STEP_SUMMARY
+          echo '| Format | ${{ steps.ruff-format.conclusion == 'failure' && '❌' || ' ✅' }} |' >> $GITHUB_STEP_SUMMARY
+          echo '| Lint | ${{ steps.ruff-lint.conclusion == 'failure' && '❌' || ' ✅' }} |' >> $GITHUB_STEP_SUMMARY
+          echo '| XML / ZCML | ${{ steps.zpretty.conclusion == 'failure' && '❌' || ' ✅' }} |' >> $GITHUB_STEP_SUMMARY
+          echo '| Python Versions | ${{ steps.py-versions.conclusion == 'failure' && '❌' || ' ✅' }} |' >> $GITHUB_STEP_SUMMARY
 
   test:
     name: "Backend: Test"
diff --git a/AGENTS.md b/AGENTS.md
@@ -6,6 +6,8 @@ This document contains the guidelines, commands, and code style rules for AI cod
 
 This project uses `make` as the primary task runner, backed by `uv` for Python environment management and `hatchling` as the build system.
 
+**IMPORTANT MANDATE**: After you modify *any* Python, XML, ZCML, or PT file, you MUST run `make check` (or `make format && make lint`) and fix any resulting errors before completing your task.
+
 ### Installation and Running
 - **Install the project**: 
   ```bash
diff --git a/Makefile b/Makefile
@@ -100,7 +100,7 @@ create-site: $(VENV_FOLDER) instance/etc/zope.ini ## Create a new site from scra
 lint: ## Check and fix code base according to Plone standards
 	@echo "$(GREEN)==> Lint codebase$(RESET)"
 	@uvx ruff@latest check --fix --config $(BACKEND_FOLDER)/pyproject.toml
-	@uvx pyroma@latest -d .
+	@uvx --with=hatchling pyroma@latest -d .
 	@uvx check-python-versions@latest .
 	@uvx zpretty@latest --check src
 
diff --git a/docs/docs/conf.py b/docs/docs/conf.py
@@ -5,10 +5,10 @@
 # -- Path setup --------------------------------------------------------------
 
 from datetime import datetime
-
 from packaging.version import Version
 from plone_sphinx_theme import __version__
 
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -24,7 +24,7 @@
 trademark_name = "codesyntax"
 now = datetime.now()
 year = str(now.year)
-copyright = year
+copyright = year  # noqa: A001
 
 
 # The version info for the project you're documenting, acts as replacement for
@@ -69,6 +69,7 @@
     "sphinx_copybutton",
     "sphinx_design",
     "sphinx_examples",
+    "sphinx_llms_txt",
     "sphinx_reredirects",
     "sphinx_sitemap",
     "sphinx_tippy",
@@ -100,8 +101,8 @@
     r"https://github.com/.*#.*",
     # Ignore other specific anchors
 ]
-linkcheck_allowed_redirects = {  # TODO: Confirm usage of linkcheck_allowed_redirects
-    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
+linkcheck_allowed_redirects = {
+    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".  # noqa: E501
 }
 linkcheck_anchors = True
 linkcheck_timeout = 5
@@ -131,7 +132,7 @@
 html_theme = "plone_sphinx_theme"  # This can be configured
 html_logo = "_static/logo.svg"
 html_favicon = "_static/favicon.svg"
-# The default value includes icon-links, so override it with that one omitted, and add it to html_theme_options[footer_content_items].
+# The default value includes icon-links, so override it with that one omitted, and add it to html_theme_options[footer_content_items].  # noqa: E501
 html_sidebars = {
     "**": [
         "navbar-logo",
@@ -141,8 +142,8 @@
 }
 html_theme_options = {
     "article_header_start": ["toggle-primary-sidebar"],
-    # "extra_footer": """<p>Example `extra_footer` content. License info. Trademark info and usage.</p>
-    # <p>Pull request previews by <a href="https://readthedocs.org/">Read the Docs</a>.</p>""",
+    # "extra_footer": """<p>Example `extra_footer` content. License info. Trademark info and usage.</p>  # noqa: E501
+    # <p>Pull request previews by <a href="https://readthedocs.org/">Read the Docs</a>.</p>""",  # noqa: E501
     "footer_content_items": [
         "author",
         "copyright",
@@ -247,12 +248,12 @@
 myst_enable_extensions = [
     "attrs_block",  # Support parsing of block attributes.
     "attrs_inline",  # Support parsing of inline attributes.
-    "colon_fence",  # You can also use ::: delimiters to denote code fences, instead of ```.
-    "deflist",  # Support definition lists. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists
-    "html_image",  # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images
+    "colon_fence",  # You can also use ::: delimiters to denote code fences, instead of ```.  # noqa: E501
+    "deflist",  # Support definition lists. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#definition-lists  # noqa: E501
+    "html_image",  # For inline images. See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#html-images  # noqa: E501
     "linkify",  # Identify "bare" web URLs and add hyperlinks.
-    "strikethrough",  # See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-strikethrough
-    "substitution",  # Use Jinja2 for substitutions. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2
+    "strikethrough",  # See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-strikethrough  # noqa: E501
+    "substitution",  # Use Jinja2 for substitutions. https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2  # noqa: E501
 ]
 
 myst_substitutions = {}
diff --git a/docs/docs/how-to-guides/custom-row-view.md b/docs/docs/how-to-guides/custom-row-view.md
@@ -61,7 +61,7 @@ Next, register the view in your `configure.zcml` so Plone knows it exists. It is
 
 ```xml
 <browser:page
-    name="myaddon-video-embed-view"
+    name="cs_dynamicpages-myaddon-video-embed-view"
     for="cs_dynamicpages.content.dynamic_page_row.IDynamicPageRow"
     template="video_embed_view.pt"
     permission="zope2.View"
@@ -85,7 +85,7 @@ You must register it in the {term}`Dynamic Pages Registry` (`IDynamicPagesContro
     <value purge="False">
       <element>
         <!-- The ZCML name of your view -->
-        <key name="row_type">myaddon-video-embed-view</key>
+        <key name="row_type">cs_dynamicpages-myaddon-video-embed-view</key>
         
         <!-- The icon to display in the dropdown (Bootstrap/Plone icon name) -->
         <key name="row_type_icon">play-btn</key>
diff --git a/docs/pyproject.toml b/docs/pyproject.toml
@@ -30,6 +30,7 @@ dev = [
     "sphinx-copybutton",
     "sphinx-design",
     "sphinx-examples",
+    "sphinx-llms-txt",
     "sphinx-notfound-page",
     "sphinx-reredirects",
     "sphinx-sitemap",
diff --git a/docs/uv.lock b/docs/uv.lock
diff --git a/news/+llm.internal b/news/+llm.internal
@@ -0,0 +1 @@
+Add llms plugin for documentation @erral
diff --git a/news/+tests.internal b/news/+tests.internal
@@ -0,0 +1 @@
+Add tests for documentation how-tos @erral
diff --git a/src/cs_dynamicpages/tests/how_tos/__init__.py b/src/cs_dynamicpages/tests/how_tos/__init__.py
diff --git a/src/cs_dynamicpages/tests/how_tos/test_configure_registry.py b/src/cs_dynamicpages/tests/how_tos/test_configure_registry.py
@@ -0,0 +1,75 @@
+from cs_dynamicpages.testing import CS_DYNAMICPAGES_INTEGRATION_TESTING
+from plone.app.testing import setRoles
+from plone.app.testing import TEST_USER_ID
+
+import unittest
+
+
+class TestHowToConfigureRegistry(unittest.TestCase):
+    layer = CS_DYNAMICPAGES_INTEGRATION_TESTING
+
+    def setUp(self):
+        self.portal = self.layer["portal"]
+        setRoles(self.portal, TEST_USER_ID, ["Manager"])
+
+    def test_configure_row_widths(self):
+        """Test adding a custom row width to the registry."""
+        from plone import api
+
+        record_name = "cs_dynamicpages.dynamic_pages_control_panel.row_widths"
+        current_widths = list(api.portal.get_registry_record(record_name))
+
+        new_width = {
+            "row_width_label": "Extra Narrow",
+            "row_width_class": "col-md-4 offset-md-4",
+        }
+
+        current_widths.append(new_width)
+        api.portal.set_registry_record(record_name, current_widths)
+
+        # Verify it was added
+        updated_widths = api.portal.get_registry_record(record_name)
+        self.assertEqual(updated_widths[-1]["row_width_label"], "Extra Narrow")
+        self.assertEqual(updated_widths[-1]["row_width_class"], "col-md-4 offset-md-4")
+
+        # Test vocabulary behavior
+        from zope.component import getUtility
+        from zope.schema.interfaces import IVocabularyFactory
+
+        vocab_factory = getUtility(IVocabularyFactory, name="cs_dynamicpages.RowWidth")
+        vocab = vocab_factory(self.portal)
+
+        # Check that the new width is in the vocabulary
+        self.assertIn("col-md-4 offset-md-4", [term.value for term in vocab])
+
+    def test_configure_spacers(self):
+        """Test modifying spacers in the registry (e.g., Tailwind classes)."""
+        from plone import api
+
+        record_name = "cs_dynamicpages.dynamic_pages_control_panel.spacer_padding_top"
+        current_spacers = list(api.portal.get_registry_record(record_name))
+
+        new_spacer = {
+            "spacer_label": "Large (Tailwind)",
+            "spacer_class": "pt-12",
+        }
+
+        current_spacers.append(new_spacer)
+        api.portal.set_registry_record(record_name, current_spacers)
+
+        # Verify it was added
+        updated_spacers = api.portal.get_registry_record(record_name)
+        self.assertEqual(updated_spacers[-1]["spacer_label"], "Large (Tailwind)")
+        self.assertEqual(updated_spacers[-1]["spacer_class"], "pt-12")
+
+        # Test vocabulary behavior
+        from zope.component import getUtility
+        from zope.schema.interfaces import IVocabularyFactory
+
+        vocab_factory = getUtility(
+            IVocabularyFactory, name="cs_dynamicpages.RowPaddingTop"
+        )
+        vocab = vocab_factory(self.portal)
+
+        # Check that the new spacer is in the vocabulary
+        self.assertIn("pt-12", [term.value for term in vocab])
diff --git a/src/cs_dynamicpages/tests/how_tos/test_custom_row_view.py b/src/cs_dynamicpages/tests/how_tos/test_custom_row_view.py
@@ -0,0 +1,86 @@
+from cs_dynamicpages.testing import CS_DYNAMICPAGES_INTEGRATION_TESTING
+from plone.app.testing import setRoles
+from plone.app.testing import TEST_USER_ID
+from zope.component import getUtility
+
+import unittest
+
+
+class TestHowToCustomRowView(unittest.TestCase):
+    layer = CS_DYNAMICPAGES_INTEGRATION_TESTING
+
+    def setUp(self):
+        self.portal = self.layer["portal"]
+        self.request = self.layer["request"]
+        setRoles(self.portal, TEST_USER_ID, ["Manager"])
+
+        # Create a dynamic page folder and row
+        self.portal.invokeFactory("DynamicPageFolder", "page1", title="Page 1")
+        self.page = self.portal["page1"]
+        self.page.invokeFactory("DynamicPageRow", "row1", title="Row 1")
+        self.row = self.page["row1"]
+
+    def test_add_custom_row_view_to_registry(self):
+        """Test step 3 from custom-row-view.md how-to."""
+        from plone import api
+
+        # This is the dict we want to add to the registry according to the docs
+        new_row_type = {
+            "row_type": "cs_dynamicpages-myaddon-video-embed-view",
+            "row_type_icon": "play-btn",
+            "row_type_has_featured_add_button": False,
+            "each_row_type_fields": [
+                "IBasic.title",
+                "IBasic.description",
+                "IRichTextBehavior-text",
+                "IRowWidth.width",
+                "IExtraClass.extra_class",
+                "IRowVerticalSpacing.padding_top",
+                "IRowVerticalSpacing.padding_bottom",
+                "IRowVerticalSpacing.margin_top",
+                "IRowVerticalSpacing.margin_bottom",
+            ],
+        }
+
+        # To make schema validation pass during test, we need to register a dummy view
+        # adapter so the vocabulary finds it when checking 'row_type' value constraints
+        from cs_dynamicpages.content.dynamic_page_row import IDynamicPageRow
+        from zope.component import getSiteManager
+        from zope.interface import Interface
+        from zope.publisher.interfaces.browser import IBrowserRequest
+
+        class DummyView:
+            pass
+
+        sm = getSiteManager()
+        sm.registerAdapter(
+            DummyView,
+            (IDynamicPageRow, IBrowserRequest),
+            Interface,
+            name="cs_dynamicpages-myaddon-video-embed-view",
+        )
+
+        # Append it to the existing record using plone.api
+        record_name = "cs_dynamicpages.dynamic_pages_control_panel.row_type_fields"
+        current_rows = list(api.portal.get_registry_record(record_name))
+        current_rows.append(new_row_type)
+        api.portal.set_registry_record(record_name, current_rows)
+
+        # Verify it was added
+        updated_rows = api.portal.get_registry_record(record_name)
+        self.assertEqual(
+            updated_rows[-1]["row_type"], "cs_dynamicpages-myaddon-video-embed-view"
+        )
+        self.assertEqual(updated_rows[-1]["row_type_icon"], "play-btn")
+        self.assertFalse(updated_rows[-1]["row_type_has_featured_add_button"])
+
+        # Test vocabulary behavior
+        from zope.schema.interfaces import IVocabularyFactory
+
+        vocab_factory = getUtility(IVocabularyFactory, name="cs_dynamicpages.RowType")
+        vocab = vocab_factory(self.portal)
+
+        # Check that the new row type is in the vocabulary
+        self.assertIn(
+            "cs_dynamicpages-myaddon-video-embed-view", [term.value for term in vocab]
+        )
diff --git a/src/cs_dynamicpages/tests/how_tos/test_using_query_columns.py b/src/cs_dynamicpages/tests/how_tos/test_using_query_columns.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Add llms plugin for documentation @erral`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+Add tests for documentation how-tos @erral`