Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix: Format in README for list and consistencies #344

Open
wants to merge 7 commits into
base: 5.x
Choose a base branch
from
Open

Fix: Format in README for list and consistencies #344

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bc9d9e7
fix: ordered list indentations
adiati98 Nov 14, 2024
0690871
fix: add spaces to follow markdown rules
adiati98 Nov 14, 2024
177ed71
fix: remove double words
adiati98 Nov 14, 2024
2f646da
fix: add backticks and single quote for consistency
adiati98 Nov 14, 2024
d53a6b1
fix: versions for clarity
adiati98 Nov 19, 2024
7fc9e19
fix: remove the whole translations section
adiati98 Nov 19, 2024
d0ebfbe
Merge branch '5.x' of https://github.com/adiati98/mautic-user-documen…
adiati98 Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 24 additions & 28 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,30 +27,22 @@ 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 <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`.
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 `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`.

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.

### 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]
Expand All @@ -65,29 +57,33 @@ 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add something here about using DDEV - you can just run 'ddev config' and state docs/build/html as the root, then 'ddev start' and it'll run a web server for you. it's how we work with mautic/mautic so most folks are used to it.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't run/done this myself, so I don't want to assume. 😅
But I have a question for clarification.

Do you want to add a step using DDEV or do you want to change the step here with using DDEV?

Also, can you please point me to docs or instructions about DDEV?

Thank you.


### Vale

Before pushing, run Vale and address suggestions and errors as applicable.
1. Install [`vale`][Vale]

1. Install [`vale`][Vale]
2. `vale .`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd recommend here that we suggest they use VSCode which has the Vale extension configured. As they save their work, it'll underline/highlight issues. See the write up I made here: https://github.com/mautic/mautic-community-handbook/blob/main/docs/contributing/contributing_docs_rst.rst - perhaps we can link to this in the future, at the moment we're still in the process of converting the handbook over to Read the Docs so it's not live anywhere yet.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does something like this work?

To work with Vale, we recommend using VSCode as it has the Vale extension configured.

And then, remove the instructions here. Once the handbook is done, we can link it here.

Any thoughts?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You do need to install Vale first on your local computer, but then using VSCode works very well as we have all the VSCode extensions pre-defined. So maybe something like:

Note: We recommend using VSCode as this repository has all the extensions pre-defined. Other editors will probably have their own Vale linter plugins which help to identify problems as you type and suggest fixes.

You can use the note admonition: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/notes_warnings.html#notes

Copy link
Author

@adiati98 adiati98 Nov 19, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see.

A quick question, as this README is written in Markdown (not RST) and live on GitHub, should we use the GitHub admonition instead?


### 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

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

<img width="753" alt="Screen Shot 2021-10-06 at 15 52 06" src="https://user-images.githubusercontent.com/63312/136281761-204861f9-340a-4e3e-8ce5-e0584236303c.png">
<img width="753" alt="Screen Shot 2021-10-06 at 15 52 06" src="https://user-images.githubusercontent.com/63312/136281761-204861f9-340a-4e3e-8ce5-e0584236303c.png">

[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/

[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)):
Expand Down