Fix: Read the Docs, build and prose failed in branch 4.x, and add DDEV configuration

.ddev/commands/web/build-docs

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+
+## Description: Build User documentation using the Sphinx HTML builder.
+## Usage: build-docs
+## Example: ddev build-docs
+
+# Ensure we fail on error
+set -e
+
+# Initialize terminal colors/styles
+bold=$(tput bold)
+green=$(tput setaf 2)
+reset=$(tput sgr0)
+underline=$(tput smul)
+
+echo "${bold}${green}🔧 Building user documentation...${reset}"
+
+# Ensure we're in the right directory
+cd /var/www/html/docs
+echo
+
+# Run the build
+make html
+
+# Success message
+echo
+echo "${green}✅ Documentation build completed successfully!${reset}"
+echo "${green}📁 The HTML pages are in: ${bold}/var/www/html/docs/build/html${reset}"
+
+# Friendly access hint
+echo "${green}🌐 View the documentation at: ${bold}${underline}https://${DDEV_HOSTNAME}${reset}"
+echo

.ddev/config.yaml

@@ -0,0 +1,8 @@
+type: generic
+docroot: "docs/build/html"
+working_dir:
+  web: /var/www/html/docs
+omit_containers: [db]
+hooks:
+  post-start:
+    - exec: "make html"

.ddev/web-build/Dockerfile.sphinx

@@ -0,0 +1,16 @@
+# Update package list and install Python 3 tools: pip and venv
+RUN apt-get update && apt-get install -y python3-pip python3-venv
+
+# Define the virtual environment location and create it
+ENV VENV_DIR=/opt/mautic-docs-venv
+RUN python3 -m venv $VENV_DIR
+
+# Copy Python dependencies into the container and install them in the virtualenv
+COPY requirements.txt /tmp/requirements.txt
+RUN . $VENV_DIR/bin/activate && pip install --upgrade pip && pip install -r /tmp/requirements.txt
+
+# Ensure the virtualenv's bin directory is added to PATH so that its tools (like sphinx-build) are accessible in all contexts
+ENV PATH="$PATH:/opt/mautic-docs-venv/bin"
+
+# Persist the updated PATH for interactive shells (e.g., when using `ddev ssh`)
+RUN echo 'export PATH="$PATH:$VENV_DIR/bin"' > /etc/profile.d/venv-path.sh

.ddev/web-build/requirements.txt

@@ -0,0 +1,11 @@
+# File: docs/requirements.txt
+
+# Defining the exact version will make sure things don't break
+sphinx==8.0.2
+sphinx_rtd_theme==3.0.0
+readthedocs-sphinx-search==0.3.2
+rstcheck==6.2.4
+myst-parser==4.0.0
+linkify-it-py==2.0.3
+esbonio==0.16.5
+attrs==24.2.0

.devcontainer/devcontainer.json

@@ -0,0 +1,21 @@
+{
+	"image": "python:3.11-bookworm",
+	"features": {
+		"ghcr.io/devcontainers/features/common-utils:2": {}
+	},
+	"customizations": {
+		"vscode": {
+			"settings": {
+				"python.defaultInterpreterPath": "/usr/local/bin/python"
+			},
+			"extensions": [
+				"ms-python.python",
+				"swyddfa.esbonio",
+				"lextudio.restructuredtext",
+				"eamodio.gitlens",
+				"trond-snekvik.simple-rst"
+			]
+		}
+	},
+	"postCreateCommand": "chmod +x .devcontainer/setup-project.sh && .devcontainer/setup-project.sh"
+}

.devcontainer/setup-project.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -ex
+
+VALE_VERSION=3.7.1
+
+# Install required packages
+pip install -r docs/requirements.txt
+
+# Required for Vale
+pip install rst2html rstcheck
+
+# Install Vale
+mkdir -p /tmp/vale
+curl -sSL https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz | tar -xz -C /tmp/vale
+sudo install -o root -g root -m 0755 /tmp/vale/vale /usr/local/bin/vale
+rm -rf /tmp/vale

.github/workflows/linting.yml

@@ -4,18 +4,26 @@ on:
 
 jobs:
   prose:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04 # See https://github.com/errata-ai/vale-action/issues/128 before upgrading
     steps:
     - name: Checkout
       uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+        cache: 'pip'
+
+    - name: Install Python dependencies
+      run: pip3 install -r docs/requirements.txt
+
     - name: Vale
       uses: errata-ai/vale-action@reviewdog
       with:
         # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
-        version: 2.29.2
+        version: 3.7.1
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -39,4 +47,4 @@ jobs:
 
     - name: Check links
       working-directory: docs
-      run: make checklinks
+      run: make checklinks

.gitignore

@@ -2,6 +2,12 @@
 # Created by https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,jupyternotebooks
 
+### PHPStorm ###
+.idea
+
+### Mac OS ###
+.DS_Store
+
 ### JupyterNotebooks ###
 # gitignore template for Jupyter Notebooks
 # website: http://jupyter.org/
@@ -152,4 +158,4 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 
-# End of https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks
+# End of https://www.toptal.com/developers/gitignore/api/python,jupyternotebooks

.gitpod.Dockerfile

@@ -1,8 +1,7 @@
-FROM python:3.10
+FROM python:3.11
 
-# Don't update to a higher version until this issue has been fixed: https://github.com/errata-ai/vale/issues/528
 # Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
-ENV VALE_VERSION=2.29.2
+ENV VALE_VERSION=3.7.1
 
 WORKDIR /workspace
 
@@ -18,4 +17,4 @@ ENV PATH=/home/gitpod/.local/bin:$PATH
 # Create the gitpod user. UID must be 33333. https://www.gitpod.io/docs/configure/workspaces/workspace-image#use-a-custom-dockerfile
 RUN useradd -l -u 33333 -G sudo -md /home/gitpod -s /bin/bash -p gitpod gitpod
 
-USER gitpod
+USER gitpod

.gitpod.yml

@@ -1,6 +1,5 @@
-# Since Gitpod doesn't support caching custom Dockerfiles yet, we temporarily
-# use this once which has Python 3.9 and Vale preinstalled.
-image: dennisameling/python-vale:latest
+image: 
+  file: .gitpod.Dockerfile
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -9,7 +8,7 @@ tasks:
 vscode:
   extensions:
     - ms-python.python
-    - lextudio.restructuredtext
+    - lextudio.restructuredtext@190.1.4 # See https://github.com/mautic/user-documentation/pull/334#issuecomment-2405922370 before upgrading.
     - trond-snekvik.simple-rst
     - errata-ai.vale-server
     - eamodio.gitlens

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.9"
+    python: "3.11"
     # You can also specify other tool versions:
     # nodejs: "16"
     # rust: "1.55"

docs/conf.py

@@ -61,7 +61,7 @@
 
 # -- Internationalisation configuration
 
-locale_dirs = 'locale'
+locale_dirs = ['locale']
 
 # Please add links here that do not pass the "make checklinks" check.
 # A little context on the reason for ignoring is greatly appreciated!
@@ -74,4 +74,17 @@
     r"https://support.twilio.com/*",
     # This is a demo URL and should not be checked
     r"https://api-ssl.bitly.com/*",
-]
+    # This domain blocks the checker (403 Client Error).
+    r"https://linuxize.com/*",
+    # The GitHub Search UI requires users to be authenticated with session cookies, which we can't set up programmatically
+    r"https://github.com/search*",
+    # Requires authentication.
+    r"https://www.maxmind.com/en/accounts/current*",
+    # 403 client error from these domains
+    r"https://www.maxmind.com/en/home",
+    r"https://www.maxmind.com/en/geolite2/signup",
+    r"https://support.maxmind.com/hc/en-us/search*",
+    r"https://dev.mysql.com/doc/refman/5.7/en/regexp.html",
+    # 400 client error from this domain
+    r"https://developers.facebook.com/products/facebook-login/",
+]

docs/links/maxmind_ccpa.py

@@ -2,6 +2,6 @@
 
 link_name = "MaxMind website" 
 link_text = "MaxMind website" 
-link_url = "https://blog.maxmind.com/search-results?q=ccpa" 
+link_url = "https://support.maxmind.com/hc/en-us/search?utf8=%E2%9C%93&query=ccpa" 
 
 link.xref_links.update({link_name: (link_text, link_url)})

docs/requirements.txt

@@ -1,11 +1,11 @@
 # File: requirements.txt
 
 # Defining the exact version will make sure things don't break
-sphinx==4.2.0
-sphinx_rtd_theme==1.0.0
-readthedocs-sphinx-search==0.1.0
-rstcheck==3.3.1
-myst-parser==0.16.1 
-linkify-it-py==1.0.3
-esbonio==0.13.0
-attrs==21.4.0
+sphinx==8.0.2
+sphinx_rtd_theme==3.0.0
+readthedocs-sphinx-search==0.3.2
+rstcheck==6.2.4
+myst-parser==4.0.0 
+linkify-it-py==2.0.3
+esbonio==0.16.5
+attrs==24.2.0