Docs code style

[stevepiercy]

See #3263 and https://pyramid-stevepiercy.readthedocs.io/en/docs-style-guide/documentation-style-guide.html#source-code from #3327

[mmerickel]

@stevepiercy have you investigated any options for enforcing linting/style guides on the rst?

[stevepiercy]

I had not considered adding some automated checking, but that's a good idea. I'd create a separate PR for this new feature.

I follow what Plone and WriteTheDocs do.

Some stuff can be automated without too much difficulty, and would be helpful and unobtrusive:

• spellcheck
• linkcheck
• reST linter

There's also dozens of other projects that look for passive voice, "weasel words", and other linguistic violations, but I feel that's overkill and beyond our resources as an open source project to enforce. I think it would turn off contributors to have a Language Police robot.

If I were to implement any new CI stuff, I would probably create another environment, docs-opt, and allow failures until we have a good feel for whether it should be a hard fail, just for info, or dropped from the CI run.

I think that would be a good start because it's better than our simple make doctest html epub Sphinx builders.

Let me know your thoughts.

[mmerickel]

@stevepiercy my interest would be in maintaining syntax consistency more than anything related to spelling/grammar. We can leave that for a separate PR but I think it's important if you want to start enforcing these things that they be automated.