Use the local dockerfile over the image

.github/workflows/linting.yml

@@ -4,7 +4,7 @@ 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
@@ -15,7 +15,7 @@ jobs:
       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 }}
 

.gitpod.Dockerfile

@@ -1,8 +1,7 @@
 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
 

.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

.vscode/settings.json

@@ -5,5 +5,8 @@
     "esbonio.sphinx.buildDir": "${workspaceFolder}/build",
     "esbonio.sphinx.confDir": "${workspaceFolder}/docs",
     "restructuredtext.pythonRecommendation.disabled": true,
-    "restructuredtext.preview.name": "sphinx"
+    "restructuredtext.preview.name": "sphinx",
+    "esbonio.sphinx.pythonCommand": "python3",
+    "esbonio.sphinx.buildCommand": "sphinx-build",
+    "esbonio.logging.level": "debug"
 }

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!
@@ -76,4 +76,11 @@
     r"https://api-ssl.bitly.com/*",
     #This domain blocks the checker.
     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*",
+    # The URLs below broken and should be replaced by working ones.
+    r"https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html",
+    r"https://blog.maxmind.com/search-results*"
 ]

docs/links/github_search_ini.py

@@ -0,0 +1,7 @@
+from . import link
+
+link_name = "Mautic INI files" 
+link_text = "Mautic INI files" 
+link_url = "https://github.com/search?q=repo%3Amautic%2Fmautic+Dashboard+menu+language%3AINI" 
+
+link.xref_links.update({link_name: (link_text, link_url)})

docs/links/linux_ls_command_documentation.py

@@ -2,6 +2,6 @@
 
 link_name = "Linux ls command" 
 link_text = "Linux ls command documentation" 
-link_url = "https://www.garron.me/en/go2linux/ls-file-permissions.html" 
+link_url = "https://en.wikipedia.org/wiki/Ls" 
 
 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==6.2.1
-sphinx_rtd_theme==1.2.0
+sphinx==8.0.2
+sphinx_rtd_theme==3.0.0
 readthedocs-sphinx-search==0.3.2
-rstcheck==6.1.1
-myst-parser==1.0.0 
-linkify-it-py==2.0.0
-esbonio==0.16.0
-attrs==22.2.0
+rstcheck==6.2.4
+myst-parser==4.0.0 
+linkify-it-py==2.0.3
+esbonio==0.16.5
+attrs==24.2.0

docs/translations/translations.rst

@@ -89,7 +89,7 @@
 
 Try searching for 'Dashboard menu' within the Mautic/Mautic repository, as there is special translation for the menu item and another for the page title. GitHub won't find the right translation when you search for just 'Dashboard' - it requires the full string. Next, use the filter to show only INI files. Here is the link to the search result:
 
-`https://github.com/mautic/mautic/search?l=INI&q=Dashboard+menu <https://github.com/mautic/mautic/search?l=INI&q=Dashboard+menu>`_
+:xref:`Mautic INI files`
 
 The first file found is ``app/bundles/DashboardBundle/Translations/en_US/messages.ini`` and there is the line ``mautic.dashboard.menu.index="Dashboard"`` within the file, which is text to override.
 

docs/troubleshooting/troubleshooting.rst

@@ -113,7 +113,7 @@ This error reported is:
 
 This means that the memory limit that Apache has available is too low. Edit the ``memory_limit`` in the ``php.ini`` configuration file. 
 
-Read more about this in :doc:`./troubleshooting/working_with_resource_limits`.
+Read more about this in :doc:`/troubleshooting/working_with_resource_limits`.
 
 A required PHP extension is missing
 ===================================