Merge main 👉🏻 5.x TEDU-140

.all-contributorsrc

@@ -59,6 +59,24 @@
       "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,

.github/workflows/linting.yml

@@ -1,35 +1,31 @@
 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
     steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
       with:
         fetch-depth: 0
 
     - 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: 2.29.2
       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'

.gitpod.Dockerfile

@@ -0,0 +1,21 @@
+FROM python:3.10
+
+# 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
+
+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

.vscode/welcome.md

@@ -1,9 +1,9 @@
-Welcome to the Mautic end user documentation editor!
+Welcome to the Mautic End User documentation editor., open
 
-We've already set up everything you need. To get started, follow these steps:
-1. Open a file in the `docs/` folder (files that end with `.rst` are docs files)
-2. Click the magnifier icon in the top right corner to see a LIVE preview of the file you're editing
+Everything you need is already set up. To get started, follow these steps:
+1. Open a file in the `docs/` folder - files that end with `.rst` are docs files.
+2. Click the magnifier icon in the top right corner to see a live preview of the file you're editing.
 
 Pretty cool, right?
 
-Happy writing!
+Happy writing.

README.md

@@ -1,6 +1,6 @@
 [![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-6-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-8-orange.svg?style=flat-square)](#contributors-)
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
@@ -17,6 +17,40 @@
 
 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
+
+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 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 - 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.
+
+### 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 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
+
 ## Build documentation locally
 
 - [RST Syntax Cheatsheet][RST Cheatsheet]
@@ -28,9 +62,10 @@
 1. Install Python 3 for your OS if not already installed
 2. Install Sphinx `pip install sphinx`
 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.
+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.
 
 ### Vale
 Before pushing, run Vale and address suggestions and errors as applicable.
@@ -69,6 +104,10 @@
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/kukis2107"><img src="https://avatars.githubusercontent.com/u/60287846?v=4?s=100" width="100px;" alt="kukis2107"/><br /><sub><b>kukis2107</b></sub></a><br /><a href="#translation-kukis2107" title="Translation">🌍</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/putzwasser"><img src="https://avatars.githubusercontent.com/u/26040044?v=4?s=100" width="100px;" alt="putzwasser"/><br /><sub><b>putzwasser</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/pulls?q=is%3Apr+reviewed-by%3Aputzwasser" title="Reviewed Pull Requests">👀</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Moongazer"><img src="https://avatars.githubusercontent.com/u/1685510?v=4?s=100" width="100px;" alt="Moongazer"/><br /><sub><b>Moongazer</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=Moongazer" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/patrykgruszka"><img src="https://avatars.githubusercontent.com/u/8580942?v=4?s=100" width="100px;" alt="Patryk Gruszka"/><br /><sub><b>Patryk Gruszka</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=patrykgruszka" title="Documentation">📖</a></td>
+    </tr>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Amiyah14"><img src="https://avatars.githubusercontent.com/u/45315891?v=4?s=100" width="100px;" alt="Emily"/><br /><sub><b>Emily</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=Amiyah14" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>
@@ -78,4 +117,4 @@
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
-This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

docs/authentication/authentication.rst

@@ -48,6 +48,23 @@ The IDP may ask for the following settings:
 
 #. Custom attributes - Mautic requires three custom attributes in the IDP responses for the User Email, first name and last name. Username is also supported but is optional. Configure the attribute names used by the IDP in Mautic's Configuration > User/Authentication Settings under the 'Enter the names of the attributes the configured IDP uses for the following Mautic User fields' section.
 
+Example: Azure SAML SSO
+=======================
+
+1) Register new Enterprise applications by navigating to ``Create your own Application`` and then ``Integrate any other application you don't find in the gallery (Non-gallery)``
+2) Go to Single Sign-On
+3) ``Identifier (Entity ID)`` - this is the site URL located at the top of User/Authentication Settings. Copy this exactly as is to the IDP.
+4) ``Reply URL (Assertion Consumer Service URL)`` - Use ``https://example.com/s/saml/login_check``
+5) Download Federation Metadata XML from 3. SAML Certificates
+6) Upload the downloaded Federation Metadata XML to Mautic
+7) X.509-Certificate isn't required
+8) Use the following for the custom attributes fields:
+
+E-Mail: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress``
+First Name: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname``
+Last Name: ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname``
+Username (optional): ``http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress``
+
 Logging in
 ==========
 
@@ -62,4 +79,4 @@ To turn off SAML, click the Remove link to the right of the Identity provider me
 
 .. image:: images/authentication-settings.png
   :width: 800
-  :alt: Screenshot of the authentication settings section
+  :alt: Screenshot of the authentication settings section

docs/channels/emails.rst

@@ -309,7 +309,7 @@ This is how it would be set up in Mautic's Email configuration:
 To replace the Sendgrid API key, add it to the relevant field in the Email configuration and save. Mautic now uses the Sendgrid API to send Emails. 
 
 .. warning::
-  It's a nice perk that Mautic can use any transport provided by Symfony Mailer. However, be aware that such transports (from Symfony) don't support batch sending, even via API. They only send one email per request, as opposed to a thousand emails per request as is the case with some Mautic transports, which can make them slow at scale. They also don't support transport callback handling used for bounce management. If you plan to send larger volumes of Emails or need to use features which require callback handling, please consider using Email transports built specifically for such use. These plugins are available in the :doc:`Mautic Marketplace </marketplace/marketplace.rst>`.
+  It's a nice perk that Mautic can use any transport provided by Symfony Mailer. However, be aware that such transports (from Symfony) don't support batch sending, even via API. They only send one email per request, as opposed to a thousand emails per request as is the case with some Mautic transports, which can make them slow at scale. They also don't support transport callback handling used for bounce management. If you plan to send larger volumes of Emails or need to use features which require callback handling, please consider using Email transports built specifically for such use. These plugins are available in the :doc:`Mautic Marketplace <marketplace/marketplace.rst>`.
 
 The system can either send Emails immediately or queue them for processing in batches by a :doc:`cron job </configuration/cron_jobs>`.
 

docs/conf.py

@@ -59,6 +59,10 @@
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
 
+# -- Internationalisation configuration
+
+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!
 
@@ -70,4 +74,4 @@
     r"https://support.twilio.com/*",
     # This is a demo URL and should not be checked
     r"https://api-ssl.bitly.com/*",
-]
+]