@plone/registry as ESM module, move to TS, complete documentation

.github/workflows/acceptance.yml

@@ -521,6 +521,9 @@ jobs:
       - name: Install yalc
         run: npm -g install yalc
 
+      - name: Build dependencies
+        run: make build-deps
+
       - name: Install a yalc'ed version of the current Volto in the project - publish
         run: |
           yalc publish packages/types

apps/plone/.eslintrc.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const projectRootPath = __dirname;
-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+const AddonConfigurationRegistry =
+  require('@plone/registry/addon-registry').default;
 
 let voltoPath = './node_modules/@plone/volto';
 

docs/source/upgrade-guide/index.md

@@ -509,6 +509,41 @@ The `react/jsx-key` rule has been enabled in ESlint for catching missing `key` i
 You might catch some violations in your project or add-on code after running ESlint.
 Adding the missing `key` property whenever the violation is reported will fix it.
 
+### `@plone/registry` moved to ESM
+
+The `@plone/registry` package has been moved to ESM.
+This unfortunately forces some import path changes that should be patched in your Plone project or add-on boilerplates.
+
+```{note}
+As always, when something changes in the boilerplate, you may regenerate one from Cookieplone and move your code into it, instead of fiddling with it.
+```
+
+For example, in your projects {file}`.eslintrc.js`:
+
+```diff
+ const fs = require('fs');
+ const projectRootPath = __dirname;
+-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++const AddonConfigurationRegistry =
++  require('@plone/registry/addon-registry').default;
+```
+
+also, in the Storybook configuration {file}`
+
+```diff
+       defaultRazzleOptions,
+     );
+-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
++    const AddonConfigurationRegistry =
++      require('@plone/registry/addon-registry').default;
+```
+
+```{versionadded} Volto 18.0.0-alpha.21
+```
+
+```{versionadded} @plone/scripts 3.6.1
+```
+
 (volto-upgrade-guide-17.x.x)=
 
 ## Upgrading to Volto 17.x.x

packages/generator-volto/generators/app/templates/.eslintrc.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const projectRootPath = __dirname;
-const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+const AddonConfigurationRegistry =
+  require('@plone/registry/addon-registry').default;
 
 let voltoPath = './node_modules/@plone/volto';
 

packages/generator-volto/generators/app/templates/.storybook/main.js

@@ -104,7 +104,8 @@ module.exports = {
       [],
       defaultRazzleOptions,
     );
-    const AddonConfigurationRegistry = require('@plone/registry/src/addon-registry');
+    const AddonConfigurationRegistry =
+      require('@plone/registry/addon-registry').default;
 
     const registry = new AddonConfigurationRegistry(projectRootPath);
 

packages/registry/.eslintrc.js → packages/registry/.eslintrc.cjs

@@ -16,6 +16,8 @@ module.exports = {
   // Base config
   extends: ['eslint:recommended'],
 
+  ignorePatterns: ['docs/_static/searchtools.js'],
+
   overrides: [
     // React
     {
@@ -61,7 +63,11 @@ module.exports = {
 
     // Node
     {
-      files: ['.eslintrc.js', 'src/*.js'],
+      files: [
+        '.eslintrc.cjs',
+        'src/addon-registry/**/*.{js,ts}',
+        '__tests__/**/*.{js,ts}',
+      ],
       env: {
         node: true,
         es6: true,

packages/registry/.gitignore

@@ -1,6 +1,7 @@
 .parcel-cache/
 dist
+/bin
+/lib
+/include
 
-# yarn 3
-.pnp.*
-.yarn/*
+docs/_build/

packages/registry/.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .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.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

packages/registry/Makefile

@@ -0,0 +1,86 @@
+### Defensive settings for make:
+#     https://tech.davis-hansson.com/p/make/
+SHELL:=bash
+.ONESHELL:
+.SHELLFLAGS:=-eu -o pipefail -c
+.SILENT:
+.DELETE_ON_ERROR:
+MAKEFLAGS+=--warn-undefined-variables
+MAKEFLAGS+=--no-builtin-rules
+
+# Sphinx variables
+# You can set these variables from the command line.
+SPHINXOPTS      ?=
+VALEOPTS        ?=
+# Internal variables.
+SPHINXBUILD     = "$(realpath bin/sphinx-build)"
+SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)"
+DOCS_DIR        = ./docs/
+BUILDDIR        = ./_build/
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+VALEFILES       := $(shell find $(DOCS_DIR) -type f -name "*.md" -print)
+
+# We like colors
+# From: https://coderwall.com/p/izxssa/colored-makefile-for-golang-projects
+RED=`tput setaf 1`
+GREEN=`tput setaf 2`
+RESET=`tput sgr0`
+YELLOW=`tput setaf 3`
+
+## Docs
+
+bin/python: ## Create a Python virtual environment with the latest pip, and install documentation requirements
+	python3 -m venv . || virtualenv --clear --python=python3 .
+	bin/python -m pip install --upgrade pip
+	@echo "Python environment created."
+	bin/pip install -r ../../requirements-docs.txt
+	@echo "Requirements installed."
+
+.PHONY: docs-clean
+docs-clean:  ## Clean current and legacy docs build directories, and Python virtual environment
+	rm -rf bin include lib
+	rm -rf docs/_build
+	cd $(DOCS_DIR) && rm -rf $(BUILDDIR)/
+
+.PHONY: docs-html
+docs-html: bin/python  ## Build html
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: docs-livehtml
+docs-livehtml: bin/python  ## Rebuild Sphinx documentation on changes, with live-reload in the browser
+	cd "$(DOCS_DIR)" && ${SPHINXAUTOBUILD} \
+		--ignore "*.swp" \
+		-b html . "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+.PHONY: docs-linkcheck
+docs-linkcheck: bin/python  ## Run linkcheck
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+		"or in $(BUILDDIR)/linkcheck/ ."
+
+.PHONY: docs-linkcheckbroken
+docs-linkcheckbroken: bin/python  ## Run linkcheck and show only broken links
+	cd $(DOCS_DIR) && $(SPHINXBUILD) -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 $$? -eq 0; then exit 1; fi || test $$? -ne 0
+
+.PHONY: docs-vale
+docs-vale: bin/python  ## Install (once) and run Vale style, grammar, and spell checks
+	bin/vale sync
+	bin/vale --no-wrap $(VALEOPTS) $(VALEFILES)
+	@echo
+	@echo "Vale is finished; look for any errors in the above output."
+
+.PHONY: docs-rtd-pr-preview
+docs-rtd-pr-preview: ## Build previews of pull requests that have documentation changes on Read the Docs via CI
+	pip install -r requirements-docs.txt
+	cd $(DOCS_DIR) && sphinx-build -b html $(ALLSPHINXOPTS) ${READTHEDOCS_OUTPUT}/html/
+
+## Build
+
+.PHONY: rename-to-cjs
+rename-to-cjs: ## Rename the built files js -> cjs
+	mv dist/cjs/addon-registry.js dist/cjs/addon-registry.cjs
+	mv dist/cjs/create-addons-loader.js dist/cjs/create-addons-loader.cjs
+	mv dist/cjs/create-theme-loader.js dist/cjs/create-theme-loader.cjs