From bc9d9e79a33f2db0f5414694612bb9511a873829 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 14 Nov 2024 13:08:42 +0100 Subject: [PATCH 1/6] fix: ordered list indentations --- README.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 2794f7bf..c1ff923c 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,10 @@ To make more complex changes, follow the steps below: 3. Create a working folder on your local computer. 4. Open a terminal and navigate to that folder using the command `cd `. 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`. +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`. -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. @@ -66,28 +67,29 @@ The following provides instructions for how to build docs locally for visualizat 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. -1. Install [`vale`][Vale] +1. Install [`vale`][Vale] 2. `vale .` ### PhpStorm/PyCharm File Watcher -You can automatically build changes to rst files using a 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 Screen Shot 2021-10-06 at 15 52 06 -[ReadTheDocs]: -[End user docs]: -[RTD badge URL]: -[RTD URL]: -[RST Cheatsheet]: -[Sphinx Template]: -[Sphinx Demo]: -[Vale]: +[ReadTheDocs]: https://readthedocs.org +[End user docs]: https://github.com/mautic/mautic-documentation +[RTD badge URL]: https://readthedocs.org/projects/mautic-documentation/badge/?version=latest +[RTD URL]: https://mautic-documentation.readthedocs.io/en/latest/?badge=latest +[RST Cheatsheet]: https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst +[Sphinx Template]: https://github.com/readthedocs/sphinx_rtd_theme/tree/master/docs/demo +[Sphinx Demo]: https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/structure.html +[Vale]: https://vale.sh/docs/vale-cli/installation/ + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): From 069087116a0025c0f37c7974db54b78fca9184cd Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 14 Nov 2024 13:12:26 +0100 Subject: [PATCH 2/6] fix: add spaces to follow markdown rules --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c1ff923c..c9a75b10 100644 --- a/README.md +++ b/README.md @@ -69,17 +69,20 @@ The following provides instructions for how to build docs locally for visualizat 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. + 1. Install [`vale`][Vale] 2. `vale .` ### 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 -Screen Shot 2021-10-06 at 15 52 06 - + Screen Shot 2021-10-06 at 15 52 06 [ReadTheDocs]: https://readthedocs.org [End user docs]: https://github.com/mautic/mautic-documentation From 177ed71b80bbb7a9c5ec86c3b496e2514f1db9cc Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 14 Nov 2024 15:48:26 +0100 Subject: [PATCH 3/6] fix: remove double words --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c9a75b10..682abf11 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ To make more complex changes, follow the steps below: 3. Create a working folder on your local computer. 4. Open a terminal and navigate to that folder using the command `cd `. 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`. +6. Once forked, if you know your way around Git and you 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`. From 2f646da39cac79b953709447b1a7e98fa005124b Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Thu, 14 Nov 2024 15:55:55 +0100 Subject: [PATCH 4/6] fix: add backticks and single quote for consistency --- README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 682abf11..098a77dd 100644 --- a/README.md +++ b/README.md @@ -27,19 +27,19 @@ To make more complex changes, follow the steps below: 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 `. -5. Fork the `mautic/user-documentation` repository on GitHub by clicking on the fork button at the top right. +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 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`. + 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. +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. +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. @@ -49,7 +49,7 @@ Currently, we manually create the translation files necessary for Transifex to i 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` +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 @@ -66,7 +66,7 @@ The following provides instructions for how to build docs locally for visualizat 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. +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 @@ -77,9 +77,9 @@ Before pushing, run Vale and address suggestions and errors as applicable. ### PhpStorm/PyCharm File Watcher -You can automatically build changes to rst files using a file watcher. +You can automatically build changes to `rst` files using a file watcher. -1. Go to Preferences -> Tools -> File Watchers -> + button -> custom +1. Go to `Preferences -> Tools -> File Watchers -> + button -> custom` 2. Configure the watcher as presented in the screenshot Screen Shot 2021-10-06 at 15 52 06 From d53a6b16ad809fed16a6475e8f67321b97244262 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Tue, 19 Nov 2024 21:26:18 +0100 Subject: [PATCH 5/6] fix: versions for clarity --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 098a77dd..2ee83952 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,9 @@ To make more complex changes, follow the steps below: 3. Create a working folder on your local computer. 4. Open a terminal and navigate to that folder using the command `cd `. 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 writing documentation for something which is specific to the latest version of Mautic, you should branch from `main`. +6. Once forked, if you know your way around Git and you are writing documentation for something which is specific to the latest version of Mautic, you should branch from `5.x`. - 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`. + If you are writing documentation for a feature which is coming in a future release - e.g. `6.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. `6.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. From 7fc9e19dede5aa9540bbc6e6f7e61a608ffd4434 Mon Sep 17 00:00:00 2001 From: Ayu Adiati Date: Tue, 19 Nov 2024 21:27:59 +0100 Subject: [PATCH 6/6] fix: remove the whole translations section --- README.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/README.md b/README.md index 2ee83952..cfac87c4 100644 --- a/README.md +++ b/README.md @@ -43,15 +43,6 @@ To make more complex changes, follow the steps below: 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]