From 30873613521b558acc68ef3d1736563304b41e67 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:16:32 +0200 Subject: [PATCH 01/17] update linting.yml --- .github/workflows/linting.yml | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index 6e08cd6e..60113cd2 100644 --- a/.github/workflows/linting.yml +++ b/.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 \ No newline at end of file From a326cf04892324c61d93683d07ea1fac6474df8a Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:17:25 +0200 Subject: [PATCH 02/17] update .gitpod.Dockerfile --- .gitpod.Dockerfile | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile index e345cbca..8604ecbf 100644 --- a/.gitpod.Dockerfile +++ b/.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 \ No newline at end of file From cd15bf776e1e8a3356a690a575c32799eda757c4 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:18:31 +0200 Subject: [PATCH 03/17] update requirements.txt --- docs/requirements.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 97456aaf..beceeb66 100644 --- a/docs/requirements.txt +++ b/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 \ No newline at end of file From ab3ccc3109d8fa7195159a3240330b3b12d0690c Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:21:36 +0200 Subject: [PATCH 04/17] update gitpod.yml --- .gitpod.yml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/.gitpod.yml b/.gitpod.yml index 659fc24b..bdc51320 100644 --- a/.gitpod.yml +++ b/.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 \ No newline at end of file From 8ddced2e2dbac249ec000110f0a15e9ae08625db Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:22:40 +0200 Subject: [PATCH 05/17] update .readthedocs.yaml --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 416e26bf..bc463c39 100644 --- a/.readthedocs.yaml +++ b/.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" From 13e55dd9191ecef6cfba92e4ea407b5744d7b39e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:26:05 +0200 Subject: [PATCH 06/17] add .ddev/commands/web/build-docs --- .ddev/commands/web/build-docs | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .ddev/commands/web/build-docs diff --git a/.ddev/commands/web/build-docs b/.ddev/commands/web/build-docs new file mode 100644 index 00000000..754876e7 --- /dev/null +++ b/.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 \ No newline at end of file From 9aff000f89024ad65de3a0f6da5385c81d3a7df3 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:27:09 +0200 Subject: [PATCH 07/17] add .ddev/web-build/Dockerfile.sphinx --- .ddev/web-build/Dockerfile.sphinx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .ddev/web-build/Dockerfile.sphinx diff --git a/.ddev/web-build/Dockerfile.sphinx b/.ddev/web-build/Dockerfile.sphinx new file mode 100644 index 00000000..cac1bebf --- /dev/null +++ b/.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 \ No newline at end of file From a2c4023092b7f1114fe94b7b8c27942e08bcbaaa Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:27:55 +0200 Subject: [PATCH 08/17] add .ddev/web-build/requirements.txt --- .ddev/web-build/requirements.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 .ddev/web-build/requirements.txt diff --git a/.ddev/web-build/requirements.txt b/.ddev/web-build/requirements.txt new file mode 100644 index 00000000..f247dee7 --- /dev/null +++ b/.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 From 6dd9e6375f484c86748c64c6f23e0d30d23d0c3e Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:28:41 +0200 Subject: [PATCH 09/17] add .ddev/config.yml --- .ddev/config.yml | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .ddev/config.yml diff --git a/.ddev/config.yml b/.ddev/config.yml new file mode 100644 index 00000000..a462ac19 --- /dev/null +++ b/.ddev/config.yml @@ -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" \ No newline at end of file From 1a18f35e7c8470894fb0af8b6afc87bfdb85ce59 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:29:41 +0200 Subject: [PATCH 10/17] add .devcontainer/devcontainer.json --- .devcontainer/devcontainer.json | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .devcontainer/devcontainer.json diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..a0bc34d4 --- /dev/null +++ b/.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" +} From fe362dc4f62dc8928c6160edf3fc3a9fd951f953 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:30:27 +0200 Subject: [PATCH 11/17] add .devcontainer/setup-project.sh --- .devcontainer/setup-project.sh | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .devcontainer/setup-project.sh diff --git a/.devcontainer/setup-project.sh b/.devcontainer/setup-project.sh new file mode 100644 index 00000000..5ccd23f8 --- /dev/null +++ b/.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 \ No newline at end of file From 110525e791a6e8315270f71f7d2558f03477d15f Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:47:36 +0200 Subject: [PATCH 12/17] move vocab/Mautic to config folder and rename Vocab to vocabularies --- .github/styles/{Vocab => config/vocabularies}/Mautic/accept.txt | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/styles/{Vocab => config/vocabularies}/Mautic/accept.txt (100%) diff --git a/.github/styles/Vocab/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt similarity index 100% rename from .github/styles/Vocab/Mautic/accept.txt rename to .github/styles/config/vocabularies/Mautic/accept.txt From 5d30e0a4645b3c358c9a67cba0537fab029b10cb Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:51:40 +0200 Subject: [PATCH 13/17] update build-docs file --- .ddev/commands/web/build-docs | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 .ddev/commands/web/build-docs diff --git a/.ddev/commands/web/build-docs b/.ddev/commands/web/build-docs old mode 100644 new mode 100755 From 2482a80cd979119308111852ecf8a8d2ce46f6fd Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:52:57 +0200 Subject: [PATCH 14/17] rename config.yml to config.yaml --- .ddev/{config.yml => config.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .ddev/{config.yml => config.yaml} (100%) diff --git a/.ddev/config.yml b/.ddev/config.yaml similarity index 100% rename from .ddev/config.yml rename to .ddev/config.yaml From e60f49b3a6b08a9c3d47a7c4ca68bbfdcc833d2b Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 10:56:08 +0200 Subject: [PATCH 15/17] update .gitignore --- .gitignore | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index a8c18321..828494f8 100644 --- a/.gitignore +++ b/.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 \ No newline at end of file From c9861274313ec25e4fb53a4bc604558e9915f3cb Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 11:05:20 +0200 Subject: [PATCH 16/17] update conf.py --- docs/conf.py | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0e6c1ca5..e8a528af 100644 --- a/docs/conf.py +++ b/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/", +] \ No newline at end of file From 8ed5650ae9c8c1bcf13badb0932a1ac093714029 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Wed, 17 Sep 2025 11:13:42 +0200 Subject: [PATCH 17/17] fix: link in maxmind_ccpa.py --- docs/links/maxmind_ccpa.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/links/maxmind_ccpa.py b/docs/links/maxmind_ccpa.py index bcf4b540..97267808 100644 --- a/docs/links/maxmind_ccpa.py +++ b/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)}) \ No newline at end of file