Backmerge 6.0 into 7.0

.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,12 @@
+# 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/CODEOWNERS

@@ -0,0 +1,5 @@
+# For code owners docs, see: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Global owners
+
+*  @mautic/education-team-leaders

.github/styles/config/vocabularies/Mautic/accept.txt

@@ -111,6 +111,8 @@ Schimpf
 SCP
 SendGrid
 SES
+Shortcodes
+Shortcode
 shortcode
 shortcodes
 SMS

.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/

LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright 2014 Mautic
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,93 +1,139 @@
-[![Documentation Status][RTD badge URL]][RTD URL]
-<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-[![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors-)
-<!-- ALL-CONTRIBUTORS-BADGE:END -->
+[![Documentation Status][RTD badge URL]][RTD URL] [![All Contributors](https://img.shields.io/github/all-contributors/mautic/user-documentation?color=ee8449&style=flat-square)](#contributors)
 
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
+# Mautic user documentation
 
-# Mautic user documentation (new)
-
-This repository hosts the new end-user documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://mautic-documentation.readthedocs.io/
-
-If you're looking for our current end-user documentation, please go to https://docs.mautic.org/ or the [GitHub repository][End user docs].
+This repository hosts the end-user documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://docs.mautic.org/.
 
 ## Migration of end-user docs to Read the Docs
 
 We aim to move all aspects of the end-user documentation to Read the Docs.
 
 For more background, our end goal, and to let us know if you want to help, please join the Education Team channel (#t-education) on Slack (get an invite at https://mautic.org/slack). Thanks in advance!
 
-## Making a PR
+## Local development setup
 
-To make a small change to the base language files for the documentation, use the 'edit file' button on the documentation and commit your changes. This creates a new Pull Request.
+There are two ways to set up your local environment:
 
-To make more complex changes, follow the steps below:
+### 1. With DDEV (recommended)
 
-1. Install a code editor. [Visual Studio Code](https://code.visualstudio.com) is recommended as it automatically installs all the extensions you need.
-2. Install [Github CLI](https://cli.github.com/) which simplifies Git commands.
-3. Create a working folder on your local computer.
-4. Open a terminal and navigate to that folder using the command `cd <path/to/folder>`.
-5. Fork the `mautic/user-documentation` repository on GitHub by clicking on the fork button at the top right.
-6. Once forked, if you know your way around Git and you are are writing documentation for something which is specific to the latest version of Mautic, you should branch from `main`.  
+Mautic uses [DDEV](https://ddev.com) to simplify local development and testing of documentation updates.
 
-If you are writing documentation for a feature which is coming in a future release - e.g. 5.0 - then branch off the relevant branch for that release, which should generally speaking match the branch used in the main mautic/mautic repository - e.g. `5.x`.
-7. Type `gh repo clone [your-forked-repo-name]/user-documentation` to clone your forked repository to your local computer.
-8. Open the folder `user-documentation` that is created in your editor.
-9. At the bottom left of your screen, you will see the default branch called 'main' is showing as your active branch. Click this, and a box will appear at the top of the page allowing you to 'create a new branch'. Type a name which relates to the work you plan to do.
-10. Make your desired changes by editing the files, which you can locate on the left pane.
-11. Use the Source Control icon on the menu on the left to view changed files. Click the plus icon next to them to 'stage' them for committing. This lets you save and describe changes in chunks, making it easier to reverse specific changes in the future.
-12. If editing text, ensure to run necessary commands to update files for translations on Transifex and include those updates in your PR.
-13. Commit all your changes, then click the 'Publish Branch' button. This action might prompt you to create a fork of the repository if not done earlier.
-14. Under the Source Control icon, navigate to the 'Branches' section. Find your branch, hover over the 'Create pull request' icon, and click it.
-15. This action will direct you to the GitHub web interface where you can add an appropriate title and description for your proposed changes.
-16. If reviewers request changes, switch back to the branch (as explained in step 9). Implement the necessary changes and follow steps 11-14 again. After updating, commit and push your changes, then notify the reviewer to check the updated content.
+Go to the [Get Started](https://ddev.com/get-started/) page for instructions to install DDEV on your local machine.
 
-### Generating translations files
+---
 
-Currently, we manually create the translation files necessary for Transifex to inform translators that there are changes to the content.
+> [!NOTE]
+> **For Windows users**: You can install and run DDEV on [traditional Windows](https://ddev.readthedocs.io/en/stable/#system-requirements-traditional-windows). However, it's recommended that you use [Windows Subsystem for Linux 2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) for faster and better performance.
+>
+> If you're new to WSL, follow the instructions on the [DDEV blog](https://ddev.com/blog/watch-new-windows-installer/) to install and set up WSL and DDEV. 
 
-To do this, run the following at the command line after following the steps below to build the documentation locally.
+---
 
-1. Run the command in the /docs folder `sphinx-build -b gettext . docs_translations`
-2. Commit the files created with your pull request
+After you've installed DDEV, follow these steps:
+
+1. [Fork and clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository to your local machine.
+2. Navigate into the project directory by running: 
+
+   ```bash
+   cd user-documentation
+   ```
+3. Start the DDEV environment with this command:
 
-## Build documentation locally
+   ```bash
+   ddev start
+   ```
+4. After making changes to documentation files, you need to build the updated docs by running:
+
+   ```bash
+   ddev build-docs
+   ```
+5. Run the below command to view your changes live on your browser:
+
+   ```bash
+   ddev launch
+   ```
+
+   This automatically opens your browser and navigates to `https://user-documentation.ddev.site/`.
+
+   **Note:** You must ensure that your changes work as expected. Every time you make changes, run `ddev build-docs` and refresh the page in your browser to see the changes.
+
+> [!TIP]
+> If you don't see the configuration take effect, run `ddev restart` to restart the project.
+
+### 2. With Sphinx (Python application)
 
 - [RST Syntax Cheatsheet][RST Cheatsheet]
 - [Sphinx Demo][Sphinx Demo]
 - [Sphinx Syntax][Sphinx Template]
 
 The following provides instructions for how to build docs locally for visualization without pushing to the remote:
 
-1. Install Python 3 for your OS if not already installed
+1. Install [Python 3](https://www.python.org/downloads/) for your OS if not already installed
 2. Install Sphinx `pip install sphinx`
 3. Install sphinx-rtd-theme `pip install sphinx-rtd-theme`
 4. Install MyST Parser `pip install myst_parser`
 5. CD into the docs directory `cd [path to this repo]/docs`
 6. Run `make html`
-7. This will generate HTML in docs/build/html. Setup a web server with the web root as docs/build/html or open docs/build/html/index.html in a browser.
+
+   This will generate HTML in `docs/build/html`. Setup a web server with the web root as `docs/build/html` or open `docs/build/html/index.html` in a browser.
 
-### Vale
+#### Vale
+
 Before pushing, run Vale and address suggestions and errors as applicable.
 1. Install [`vale`][Vale] 
 2. `vale .`
 
-### PhpStorm/PyCharm File Watcher
+#### PhpStorm/PyCharm File Watcher
+
 You can automatically build changes to rst files using a file watcher. 
 1. Go to Preferences -> Tools -> File Watchers -> + button -> custom
 2. Configure the watcher as presented in the screenshot
 
 <img width="753" alt="Screen Shot 2021-10-06 at 15 52 06" src="https://user-images.githubusercontent.com/63312/136281761-204861f9-340a-4e3e-8ce5-e0584236303c.png">
 
+## Generating translations files
+
+Currently, we manually create the translation files necessary for Transifex to inform translators that there are changes to the content.
+
+To do this, run the following at the command line after following the steps to build the documentation locally.
+
+1. Run the command in the `/docs` folder `sphinx-build -b gettext . docs_translations`
+2. Commit the files created with your pull request
+
 
 [ReadTheDocs]: <https://readthedocs.org>
-[End user docs]: <https://github.com/mautic/mautic-documentation>
 [RTD badge URL]: <https://readthedocs.org/projects/mautic-documentation/badge/?version=latest>
 [RTD URL]: <https://mautic-documentation.readthedocs.io/en/latest/?badge=latest>
 [RST Cheatsheet]: <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>
 [Sphinx Template]: <https://github.com/readthedocs/sphinx_rtd_theme/tree/master/docs/demo>
 [Sphinx Demo]: <https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/structure.html>
 [Vale]: <https://vale.sh/docs/vale-cli/installation/>
+
+## Making a PR
+
+To make a small change to the base language files for the documentation, use the 'edit file' button on the documentation and commit your changes. This creates a new Pull Request.
+
+To make more complex changes, follow the steps below:
+
+1. Install a code editor. [Visual Studio Code](https://code.visualstudio.com) is recommended as it automatically installs all the extensions you need.
+2. Install [GitHub CLI](https://cli.github.com/) which simplifies Git commands.
+3. Create a working folder on your local computer.
+4. Open a terminal and navigate to that folder using the command `cd <path/to/folder>`.
+5. Fork the `mautic/user-documentation` repository on GitHub by clicking on the fork button at the top right.
+6. Once forked, if you know your way around Git and you are writing documentation for something which is specific to the latest version of Mautic, you should branch from `main`.  
+
+   If you are writing documentation for a feature which is coming in a future release - for example, `5.0` - then branch off the relevant branch for that release, which should generally speaking match the branch used in the main `mautic/mautic` repository, for example, `5.x`.
+7. Type `gh repo clone [your-forked-repo-name]/user-documentation` to clone your forked repository to your local computer.
+8. Open the folder `user-documentation` that is created in your editor.
+9. At the bottom left of your screen, you will see the default branch called `main` is showing as your active branch. Click this, and a box will appear at the top of the page allowing you to 'create a new branch'. Type a name which relates to the work you plan to do.
+10. Make your desired changes by editing the files, which you can locate on the left pane.
+11. Use the Source Control icon on the menu on the left to view changed files. Click the plus icon next to them to 'stage' them for committing. This lets you save and describe changes in chunks, making it easier to reverse specific changes in the future.
+12. If editing text, ensure to run necessary commands to update files for translations on Transifex and include those updates in your PR.
+13. Commit all your changes, then click the 'Publish Branch' button. This action might prompt you to create a fork of the repository if not done earlier.
+14. Under the Source Control icon, navigate to the 'Branches' section. Find your branch, hover over the 'Create pull request' icon, and click it.
+15. This action will direct you to the GitHub web interface where you can add an appropriate title and description for your proposed changes.
+16. If reviewers request changes, switch back to the branch (as explained in step 9). Implement the necessary changes and follow steps 11-14 again. After updating, commit, and push your changes, then notify the reviewer to check the updated content.
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):