Merge pull request #177 from nick-vanpraet/fix/vale-errors-and-warnings

Fix/vale errors and warnings

.github/styles/Vocab/Mautic/accept.txt

@@ -2,14 +2,14 @@ AJAX
 allowlist
 Amazon SES
 Ameling
-Autoloader
 autoloader
-Autowired
-autowired
-Autowiring
-autowiring
+Autoloader
 autowire
+autowired
+Autowired
 autowires
+autowiring
+Autowiring
 bcc
 Beanstalkd
 Bing
@@ -23,25 +23,32 @@ Citrix
 Clearbit
 CloudAMQP
 Codecov
-config
-Config
 Company(ies)
 Composer
+Config
+config
 configurator
 ConnectWise
+Contact Points
+Continuous Integration
 Contribution(s)
 CORS
 cron
 Cron
 CTRL
 DDEV
-Do Not Contact
 DNC
+Do Not Contact
 Dripflow
 Dynamic Web Content
 FALSE
+false
+Firewalls
+firewalls
 Focus Item
 Focus Items
+Forms
+forms
 Froala
 Froogaloop
 gcm
@@ -50,12 +57,13 @@ GitBook
 GitHub
 Gitpod
 GMail
+GrapesJS Builder
 Grav
 Gravatar
 Hammerschmied
 href
-HTML
 html
+HTML
 http
 https
 HubSpot
@@ -65,41 +73,56 @@ infographics
 ISO
 JavaScript
 Joomla
+Legacy Builder
 Libre
 Licensor
 LinkedIn
 Mailjet
 Marketing Messages
 Mautic
 MaxMind
+middleware
 Middlewares
 middlewares
 MJML
 Multiselect
 multiselect
 MVP
 mysqldump
-namespace
 Namespace
+namespace
+Node.js
 noindex
 OAuth
+OAuth1a
+OAuth2
 Packagist
-PATCH
 patch
+PATCH
 PHP
+PhpStorm
+PHPUnit.xml
 Pipedrive
 Piwik
-POST
+Plugin
+Plugins
 post
+POST
 PUT
+PyCharm
 Rackspace
+Rahul
+Read the Docs
 Remarketing
+Report Email
 Salesforce
 SAML
 Schimpf
 SCP
+Segment Email
 SendGrid
 SES
+Shinde
 SMS
 SMTP
 SNS
@@ -109,29 +132,30 @@ sublicense
 SugarCRM
 Suhosin
 Symfony
+themes
+Themes
+timeframe
 Todo
 tooltip
+Tooltip
 Transifex
+Translator
 TRUE
 true
 Twilio
 unassign
 unpublish
 Unpublish
 unsubscription
+URIs
 URL
 URLs
+US
 UTM
 Vtiger
+Webhooks
 Webmecanik
 www
 YAML
 Zapier
 Zoho
-middleware
-URIs
-false
-timeframe
-OAuth1a
-OAuth2
-Tooltip

.github/workflows/linting.yml

@@ -7,32 +7,41 @@ jobs:
     runs-on: ubuntu-latest
     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@reviewdog
       with:
         # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
-        version: 2.20.2
+        version: 2.29.2
+        fail_on_error: true
       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'
 
     - name: Install Python dependencies
       run: pip3 install -r docs/requirements.txt
-    
+
     - name: Build docs
       working-directory: docs
       run: make html

.gitpod.Dockerfile

@@ -1,8 +1,8 @@
-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.20.2
+ENV VALE_VERSION=2.29.2
 
 WORKDIR /workspace
 

.gitpod.yml

@@ -1,6 +1,6 @@
-# We use a simple, custom Dockerfile that has Python and Vale preinstalled.
-image:
-  file: .gitpod.Dockerfile
+# 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
 
 tasks:
   - before: pip install -r docs/requirements.txt
@@ -13,22 +13,3 @@ vscode:
     - errata-ai.vale-server
     - eamodio.gitlens
     - trond-snekvik.simple-rst
-
-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

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

.vale.ini

@@ -1,5 +1,5 @@
 StylesPath = .github/styles
 Vocab = Mautic
-MinAlertLevel = suggestion
+MinAlertLevel = warning
 [*.{md,rst}]
 BasedOnStyles = Vale, Google, Mautic

README.md

@@ -9,14 +9,14 @@
 
 This repository hosts the new developer documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://mautic-developer.readthedocs.io/
 
-If you're looking for our legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].
+If you're looking for the legacy developer documentation, please go to https://developer.mautic.org/ or the [GitHub repository][Legacy dev docs].
 
-## Migration of developer docs to Read the Docs
+## Migration of developer docs to 'Read the Docs'
 
-We aim to move all aspects of the developer documentation to Read the Docs (with the exception of the REST API documentation).
-In the video below, [@dennisameling][dennisameling GH profile] explains how the documentation is currently structured and briefly touches upon current limitations we're running into.
+The aim is to move all aspects of the developer documentation to Read the Docs (with the exception of the REST API documentation).
+In the video below, [@dennisameling][dennisameling GH profile] explains how the documentation is currently structured and briefly touches upon current limitations.
 
-For more background, our end goal, and to let us know if you want to help, please check out [this issue][New docs background and goals]. Thanks in advance!
+For more background, the end goal, and if you want to help, please see [this issue][New docs background and goals]. Thanks in advance.
 
 [![Link to YouTube video with explanation of the current developer documentation structure][YouTube video image]][YouTube video URL]
 
@@ -48,7 +48,7 @@ The following provides instructions for how to build docs locally for visualizat
 3. Install sphinx-rtd-theme `pip install sphinx-rtd-theme`
 4. CD into the docs directory `cd [path to this repo]/docs`
 5. Run `make html`
-6. 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.
+6. This generates 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.
 
 ## Troubleshooting
 
@@ -62,8 +62,8 @@ Before pushing, run Vale and address suggestions and errors as applicable.
 1. Install [`vale`][Vale] 
 2. `vale .`
 
-### PhpStorm/PyCharm File Watcher
-You can automatically build changes to rst files using a 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
 

docs/components/emails.rst

@@ -530,20 +530,28 @@ Use the builder to do the following:
 - Go to the Advanced tab  
 - Complete the ``From Name`` & ``From Address``, ``BCC``, ``Reply-To``, ``Add Attachment``, ``custom headers``, and Click on ``Auto Generate`` to create a text version of the Email  
 - Save the Email and send a sample test, you should get everything you filled  
-
+
+.. vale off
+
 Send an individual Email
 ========================
 
+.. vale on
+
 Go to the Contacts section and select a Contact, then click Send an Email. You should be able to send an Email directly to that specific Contact's Email address.  
 
 Send a Report Email
 ===================
 
 Create a Report with any data and set it on a schedule, it should send an Email with the Report as an attachment  
-
+
+.. vale off
+
 Other Email features
 ====================
 
+.. vale on
+
 There are other places like Forget Password: they need to work as well. Please make sure you verify them. 
 
 Testing transport callback  

docs/development-environment/how_to_install_with_ddev.rst

@@ -20,11 +20,15 @@ Installing Mautic is a two-step process:
 
 1. Install Mautic running DDEV.
 
+.. vale off
+
 .. code-block:: bash
 
     cd mautic
     ddev start
 
+.. vale on
+
 .. list-table:: Users and passwords
     :header-rows: 1
 

docs/form_hooks/response_hooks.rst

@@ -47,7 +47,7 @@ Response hooks
         },
     };
 
-.. Note:: This isn't called if an onResponse hook returns TRUE.
+.. Note:: This isn't called if an :js:meth:`onResponse` hook returns TRUE.
 
 .. js:method:: onResponseEnd()
 
@@ -72,4 +72,4 @@ Response hooks
         },
     };
 
-.. Note:: This isn't called if an onResponse hook returns TRUE or if the page redirects.
+.. Note:: This isn't called if an :js:meth:`onResponse` hook returns TRUE or if the page redirects.

docs/form_hooks/validation_hooks.rst

@@ -37,7 +37,7 @@ Validation hooks
         },
     };
 
-.. Note:: This isn't called if an onValidate hook returns TRUE.
+.. Note:: This isn't called if an :js:meth:`onValidate` hook returns TRUE.
 
 
 .. js:method:: onValidateEnd()

docs/index.rst

@@ -17,7 +17,7 @@ Read all about contributing to Mautic as a Developer in the :xref:`Mautic Develo
 
 Read more about Mautic's :xref:`Mautic Code Governance` and the :xref:`Mautic Project Governance` model.
 
-Your code must follow the :xref:`Symfony coding standards`. You will find details about where Mautic deviates from these standards documented in the :doc:`/plugins/mautic_vs_symfony` section.
+Your code must follow the :xref:`Symfony coding standards`. You can find details about where Mautic deviates from these standards documented in the :doc:`/plugins/mautic_vs_symfony` section.
 
 Where to get help
 *****************