Add style guide #815
Comments
|
In Plone projects, we use Vale for checking American English spelling, grammar, and syntax, as well as checking for compliance with a style guide. We selected the Microsoft Writing Style Guide, but there are others available. We can specify our own dictionary terms as well. For example, we'd want to add |
|
I found fluffy using vale. It looks really professional. That also touches on the way we handle dependencies in icalendar as Vale is installed with pip. Also, I wonder how to use Vale with Python code documentation. How does it integrate with sphinx and restructured text? |
|
This is how Vale handles reStructuredText. Vale runs independently of Sphinx, but instead uses the underlying docutils library. Sphinx also uses docutils. In earlier iterations of Plone documentation, we used pip to install dependencies. Then we switched to We use GNU Make commands to run builds, tests, and everything else. We don't have to remember fancy command flags or options, just |
|
vale also handles HTML. We can use vale to run over the HTML documentation and test that. The Python documentation does not seem to be included otherwise but contains a lot of text. |
|
I haven't tried HTML because it requires a successful HTML build, which doesn't always happen. |
We are in the process of making the documentation nicer.
In order for it to be consistent, we should add a style guide in the maintenance section of the documentation.
See also:
@stevepiercy, could you solve (1)?
The text was updated successfully, but these errors were encountered: