This repository hosts the new end-user documentation for Mautic on the Read the Docs platform. 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.
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!
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:
- Install a code editor. Visual Studio Code is recommended as it automatically installs all the extensions you need.
- Install Github CLI which simplifies Git commands.
- Create a working folder on your local computer.
- Open a terminal and navigate to that folder using the command
cd <path/to/folder>. - Fork the
mautic/user-documentationrepository on GitHub by clicking on the fork button at the top right. - 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.
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.
- Run the command in the /docs folder
sphinx-build -b gettext . docs_translations - Commit the files created with your pull request
The following provides instructions for how to build docs locally for visualization without pushing to the remote:
- Install Python 3 for your OS if not already installed
- Install Sphinx
pip install sphinx - Install sphinx-rtd-theme
pip install sphinx-rtd-theme - Install MyST Parser
pip install myst_parser - CD into the docs directory
cd [path to this repo]/docs - Run
make html - 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.
Before pushing, run Vale and address suggestions and errors as applicable.
- Install
vale vale .
You can automatically build changes to rst files using a file watcher.
- Go to Preferences -> Tools -> File Watchers -> + button -> custom
- Configure the watcher as presented in the screenshot
Thanks goes to these wonderful people (emoji key):
 Gustavo Kennedy Renkel 🌍 |
 Roman 🌍 |
 Tomasz Kowalczyk 📖 |
 kukis2107 🌍 |
 putzwasser 👀 |
 Moongazer 📖 |
 Patryk Gruszka 📖 |
 Emily 📖 |
 John Wick 🐛 |
 jagtapreshma 📖 |
 Markus Heinilä 📖 |
 CPweb 👀 |
This project follows the all-contributors specification. Contributions of any kind welcome!