Typical common words - linting

[svx]

In order to increase the quality and also to make the docs easier to understand I wrote a linter which is able to check for typical common words.
This is handy, because with this we can make sure we always have for example GitHub and not sometimes Github, the same goes for JavaScript in place of Javascript.

Question: Do we have more words besides these two, which we should check ?

[fulv]

This probably does not apply to your linter, but it would be great if there were a "dash" checker. I can tell which pages have been touched by a german speaker, because there tend to be a lot of words that are concatenated with dashes (e.g. content-type), which is not english.

…

On Sun, Jan 29, 2017 at 6:45 AM sven ***@***.***> wrote: In order to increase the quality and also to make the docs easier to understand I wrote a linter which is able to check for *typical common words*. This is handy, because with this we can make sure we always have for example *GitHub* and not sometimes Github, the same goes for *JavaScript* in place of Javascript. Question: Do we have more words besides these two, which we should check ? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#757>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAcHxiuHUzToWG-37OoMusvlgwbjPos5ks5rXJf0gaJpZM4Lwyv_> .

[fulv]

Which is not to say that hyphens (my bad, not dashes) are never used: http://www.grammarbook.com/punctuation/hyphens.asp On Sun, Jan 29, 2017 at 8:54 AM Fulvio Casali <fulviocasali@gmail.com> wrote:

…

This probably does not apply to your linter, but it would be great if there were a "dash" checker. I can tell which pages have been touched by a german speaker, because there tend to be a lot of words that are concatenated with dashes (e.g. content-type), which is not english. On Sun, Jan 29, 2017 at 6:45 AM sven ***@***.***> wrote: In order to increase the quality and also to make the docs easier to understand I wrote a linter which is able to check for *typical common words*. This is handy, because with this we can make sure we always have for example *GitHub* and not sometimes Github, the same goes for *JavaScript* in place of Javascript. Question: Do we have more words besides these two, which we should check ? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#757>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAcHxiuHUzToWG-37OoMusvlgwbjPos5ks5rXJf0gaJpZM4Lwyv_> .

[stevepiercy]

There's a Sphinx contribution that can do this:
http://sphinxcontrib-spelling.readthedocs.io/en/latest/

There's also an open issue:
plone/plone.recipe.codeanalysis#87

And there's another open issue for an .rst linter:
plone/plone.recipe.codeanalysis#64

[svx]

@stevepiercy we are using http://sphinxcontrib-spelling.readthedocs.io/en/latest/ already and I want to get rid of it.
For 'blacklisting words' we are using on the 5.1 branch already a new linter.
We are using http://sphinxcontrib-spelling.readthedocs.io/en/latest/ for spell checks, for this it kind of works, but still the dependencies are annoying and I have other issues with it.
Further on I prefer something more light, better suited for CI and without having Sphinx as dependency. :)

[svx]

@stevepiercy for your other point, the new setup is using a reST linter:

The new setup, which is not published yet because I am still testing and tweaking is running reST syntax checks.
We decided some time ago, not to run them yet on the docs, currently the general shape of reST in our docs is still too bad and we do not want to demotivate people and so on.

I even gave a talk in Boston and a training explaining the motivation and reasons behind that.

Nothing stops you of course of doing that already, I for example run a reST test as part of my commit hook. :)

As I said above, soon this will be included as CI test for the docs.

[stevepiercy]

@svx I'd like to be a guinea pig for the new setup, as I'm considering how we can enforce compliance with our new style guide for Pyramid (and Pylons Project projects). I'm about to give up on perfection and settle for good enough.

We rely on Sphinx to build docs, and I don't see how you can build docs without it, unless you roll your own docs builder.

I always build docs before submitting a PR, and our CI for Pyramid is configured to build docs as well.

Which training was it? Got link?
https://2016.ploneconf.org/training

[svx]

@stevepiercy You can find the training in the repository of
testthedocs -> https://github.com/testthedocs/ttd.training-docs-devs.
Just note that the whole github.com/testthedocs is currently a mess, because of moving, removing, cleaning and so on :)
There will be a 'relaunch bla bla bla soon'

The trainings there are also not up2date anymore, we changed a lot of, like testing and githooks already.

Unfortunately the trainings do not contain the speaker notes, where all this is written down, bit if you really interested in the reasons and motivation we could do a hangout or something like that.

Speaking about the new setup, you can't really find it yet, because it is splattered over at least 3 different GitHub accounts in various repositories, some is not even open-source yet, cause I build it for a customer, who will open-source it somewhere next month.
I will try to collect the bits in one repo, and do a write up.
If that is done people are more than welcome to contribute, or/and give feedback.

Just to let you know, this is currently mainly written with a certain setup/structure in mind :)
The idea is to have it more flexible in the future :)

And it is also heavily opinionated, call it the CastleCMS of a docs test and build setup :).

Meaning some things you will may not like, but well maybe you or others can convince me to change certain bits or send a PR with improvements.

Oh, I almost forgot it has one dependency and this is docker, which I may change to rkt in the future.

[stevepiercy]

In Plone 6, we now use Vale. See https://6.docs.plone.org/contributing/setup-build.html#vale

This will not be fixed in previous versions.