Add overview of default local.php

.all-contributorsrc

@@ -0,0 +1,89 @@
+{
+  "files": [
+    "README.md"
+  ],
+  "imageSize": 100,
+  "commit": false,
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "gustavokennedy",
+      "name": "Gustavo Kennedy Renkel",
+      "avatar_url": "https://avatars.githubusercontent.com/u/98914036?v=4",
+      "profile": "http://overall.cloud",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "zaharovrd",
+      "name": "Roman",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8171816?v=4",
+      "profile": "http://www.youradman.com",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "tomekkowalczyk",
+      "name": "Tomasz Kowalczyk",
+      "avatar_url": "https://avatars.githubusercontent.com/u/39382654?v=4",
+      "profile": "http://adevo.pl",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "kukis2107",
+      "name": "kukis2107",
+      "avatar_url": "https://avatars.githubusercontent.com/u/60287846?v=4",
+      "profile": "https://github.com/kukis2107",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "putzwasser",
+      "name": "putzwasser",
+      "avatar_url": "https://avatars.githubusercontent.com/u/26040044?v=4",
+      "profile": "https://github.com/putzwasser",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "Moongazer",
+      "name": "Moongazer",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1685510?v=4",
+      "profile": "https://github.com/Moongazer",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "patrykgruszka",
+      "name": "Patryk Gruszka",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8580942?v=4",
+      "profile": "https://github.com/patrykgruszka",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Amiyah14",
+      "name": "Emily",
+      "avatar_url": "https://avatars.githubusercontent.com/u/45315891?v=4",
+      "profile": "https://github.com/Amiyah14",
+      "contributions": [
+        "doc"
+      ]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "skipCi": true,
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectName": "user-documentation",
+  "projectOwner": "mautic",
+  "commitType": "docs"
+}

.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/styles/Mautic/FeatureList.yml

@@ -45,6 +45,8 @@ swap:
   point actions: Point Actions
   point triggers: Point Triggers
   points: Points
+  group: Group
+  groups: Groups
   plugin: Plugin
   plugins: Plugins
   report: Report

.github/workflows/linting.yml

@@ -1,35 +1,39 @@
 name: Linting
 on:
-  # Note: onlyAnnotateModifiedLines only works correctly on PRs!
-  # If you need to run checks on push as well, create a separate workflow file.
   pull_request:
 
 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@v2
+      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@master
+      uses: errata-ai/vale-action@reviewdog
       with:
-        # We can modify these styles as we want
-        styles: |
-          https://github.com/errata-ai/Google/releases/latest/download/Google.zip
-        onlyAnnotateModifiedLines: true
+        # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
+        version: 3.7.1
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   build:
     runs-on: ubuntu-latest
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v2
+    - uses: actions/setup-python@v4
       with:
         python-version: '3.x'
         cache: 'pip'
@@ -43,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

@@ -0,0 +1,20 @@
+FROM python:3.11
+
+# Please keep version in sync with the version in .github/workflows/linting.yml for a consistent experience
+ENV VALE_VERSION=3.7.1
+
+WORKDIR /workspace
+
+# Needed for Vale (rst2html) and reStructuredText (rstcheck)
+RUN pip install rst2html rstcheck
+
+RUN mkdir -p vale && cd vale && wget https://github.com/errata-ai/vale/releases/download/v${VALE_VERSION}/vale_${VALE_VERSION}_Linux_64-bit.tar.gz && \
+    tar -xf vale_${VALE_VERSION}_Linux_64-bit.tar.gz && cp /workspace/vale/vale /usr/local/bin/vale && cd ../
+
+# /home/gitpod/.local/bin ensures that Python packages like rstcheck can be found
+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

.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,26 +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
-
-github:
-  prebuilds:
-    # enable for the master/default branch (defaults to true)
-    master: true
-    # enable for all branches in this repo (defaults to false)
-    branches: true
-    # enable for pull requests coming from this repo (defaults to true)
-    pullRequests: true
-    # enable for pull requests coming from forks (defaults to false)
-    pullRequestsFromForks: true
-    # add a check to pull requests (defaults to true)
-    addCheck: false
-    # add a "Review in Gitpod" button as a comment to pull requests (defaults to false)
-    addComment: false
-    # add a "Review in Gitpod" button to the pull request's description (defaults to false)
-    addBadge: true
-    # add a label once the prebuild is ready to pull requests (defaults to false)
-    addLabel: false
+    - eamodio.gitlens

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .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 version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "16"
+    # rust: "1.55"
+    # golang: "1.17"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# If using Sphinx, optionally build your docs in additional formats such as PDF
+# formats:
+#    - pdf
+
+# Optionally declare the Python requirements required to build your docs
+python:
+   install:
+   - requirements: docs/requirements.txt