Fix: Format in README for list and consistencies #344
Conversation
|
Hey @RCheesley, I went ahead and fix some other things here than what's required in the issue. But let me know if you want me to remove or fix them. Thank you. 🙂 |
| @@ -65,29 +66,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. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| Before pushing, run Vale and address suggestions and errors as applicable. | ||
| 1. Install [`vale`][Vale] | ||
|
|
||
| 1. Install [`vale`][Vale] | ||
| 2. `vale .` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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?
Description
This PR holds below changes in the README:
Linked Issue
Closes #343