feat: add woke setup to ReadMe
#69
Conversation
- Add section to readme.rst, describing inclusive-language setup
- Add readme.rst to .wokeignore so SP passes ``make woke`` - Add "subdirectories" to .wordlist.txt so SP passes ``make spelling``
.wokeignore
Outdated
| @@ -2,3 +2,4 @@ | |||
| # cannot avoid for now, ie | |||
| # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html | |||
| doc-cheat-sheet* | |||
| readme.rst | |||
There was a problem hiding this comment.
We should try to avoid putting a whole file here just for one paragraph. It makes sense to have this for the doc-cheat-sheets since they don't contain actual content, but we want the readme to be checked.
So it would be much better to use this as an example for inline/next-line ignoring.
There was a problem hiding this comment.
Good point. I'll revert .wokeignore and use next-line as suggested.
readme.rst
Outdated
| Suppose a file ``how-to/foo.rst`` includes a URL, that references a ``master`` | ||
| branch on some site you have no control over. You can't change the URL, and | ||
| "master" is non-inclusive language. To exempt ``foo.rst``, add the following | ||
| line to ``.wokeignore``: |
There was a problem hiding this comment.
How about splitting this up and explaining how to exclude a file AND how to add an exception within a file?
Exceptions are kinda tricky in RST, unfortunately, because the syntax doesn't really support it ... :(
But for links it's actually easy to do by putting the link at the bottom of the page and putting a comment right above it (see here for an example).
And in the paragraph here it also shouldn't be too hard, because you can just explain how to do it, which will include the required text. ;)
There was a problem hiding this comment.
Good idea - will do.
readme.rst
Outdated
| or to check all directories in your project, edit the ``woke`` target in the | ||
| ``Makefile``. For the command syntax, see the `woke User Guide |
There was a problem hiding this comment.
You also need to change .github/workflows/automatic-doc-checks.yml (or maybe we should update that to use the target from the Makefile?).
There was a problem hiding this comment.
Missed it completely - good catch!
- Revert readme.rst out of .wokeignore --- use next-line ignore instead - Separate ReadMe's woke-config description, into in-file and whole-file - Add change needed to woke command in automatic-doc-checks.yml - Add "subtree" to .wordlist.txt
make wokemake spelling