Refactor out woke instructions #158

pmatulis · 2023-12-13T22:03:10Z

Preamble: The readme.rst file in this repository is way too long. It also covers both setup and regular maintenance duties, making it hard for a contributor to find what they need once a repository has been set up by an administrator. This PR is the first of a suite of PRs for addressing the situation.

Move the details of working with inclusive language exemptions into a separate file. In so doing, the text was improved. Remove syntax highlighting for the reST code blocks as they make things look ugly and alien-like:

ru-fu

I'm okay with splitting it out if you think that improves the user experience.
However, I'm not a big fan of it because it means more content files that users need to remove from the starter pack before they can add their own content.

ru-fu · 2023-12-14T15:10:06Z

help-woke.rst

@@ -0,0 +1,46 @@
+:orphan:


Please don't use orphans, but include the file in the navigation. There's no reason to hide it.

I can do this if you feel strongly about it but the resource is intended to be accessed in the context of the README. It's a sub-page.

Yes, it can be a subpage to the readme. But I feel pretty strongly about it that all pages should always be accessible from the navigation tree - otherwise it's very easy to miss that there is another page with information.

ru-fu · 2023-12-14T15:12:48Z

help-woke.rst

+-------------
+
+To exempt an individual word, place a comment on a line immediately preceding
+the line containing the word in question. This special comment is to include


Suggested change

the line containing the word in question. This special comment is to include

the line containing the word in question. This special comment must include

Easier to understand

ru-fu · 2023-12-14T15:17:10Z

help-woke.rst

+Here is an example of an exemption that acts upon an element of a URL that is
+expressed using the link definition method (typically at the bottom of a file):


I don't find that clearer - will everyone who uses the starter pack know what the "link definition method" is?

The issue that we see a lot is that a URL contains "master", and that this is hard to fix with a comment in the line above (especially in MyST, btw). So what we should say is that for links, the best solution is to define them in a separate file or at the bottom of the page and put the comment in the line above the link definition.

I will propose something.

ru-fu · 2023-12-14T15:18:06Z

help-woke.rst

+A more drastic solution is to make an exemption for the contents of an entire
+file.
+
+Start by placing file ``.wokeignore`` into your project's root directory. Then,


The starter pack already has this file, so you only need to edit it.

ru-fu · 2023-12-14T15:19:47Z

readme.rst

+change how the ``woke`` tool is invoked from within ``docs/Makefile`` (see
+the `woke User Guide <https://docs.getwoke.tech/usage/#file-globs>`_ for help).
+
+Some circumstances may compel you to retain some non-inclusive words. In such


Suggested change

Some circumstances may compel you to retain some non-inclusive words. In such

Some circumstances might require you to use some non-inclusive words. In such

Let's keep it simple. ;)

ru-fu

Thanks! I'm happy with the text now. 🙂
But need to fix the woke test.

pmatulis · 2023-12-15T17:22:33Z

Did I miss something?

ru-fu · 2024-01-02T09:48:13Z

Did I miss something?

The doc check on the PR is red - because you have a "master" in the text without an exception.

ru-fu · 2024-01-02T15:52:51Z

help-woke.rst

+   This is your text. The word in question is here: whitelist. More text.
+
+Here is an example of an exemption that acts upon an element (the string
+wokeignore:rule=master


This won't work - it'll leave a wokeignore:rule=master both in the GitHub rendering and in the HTML output generated from RST.
I just tested this again... RST support for wokeignore is horrible. It doesn't work as described in line 18.
Let me figure something out ...

ru-fu · 2024-01-02T16:46:45Z

OK ... I couldn't find anything that doesn't feel like a hack, but this solution seems okay-ish to me:

When we merge add a custom none role that is excluded from the output canonical-sphinx-extensions#32, we'll have a :none: role that is simply dropped from the output.
We can then add :none:`wokeignore:rule=master,` to the source to make the woke check work. This will show up in the GitHub rendering (nothing we can do about that :( ), but not in the rendered HTML output.

ru-fu

It should now work to put a :none:`wokeignore:rule=master,` at the end of a line that contains a violation.
You need to include the , at the end because otherwise woke doesn't seem to parse it correctly (don't ask me why ...). And putting it in the line above also doesn't work; I haven't managed to find a workaround for that so far.

ru-fu · 2024-01-03T08:53:31Z

help-woke.rst

+   .. wokeignore:rule=whitelist
+   This is your text. The word in question is here: whitelist. More text.
+
+Here is an example of an exemption that acts upon an element (the string
+wokeignore:rule=master
+"master") of a URL. It is recommended to do this by using the standard reST
+method of placing the link at the bottom of the page (or in a separate file):


Suggested change

.. wokeignore:rule=whitelist

This is your text. The word in question is here: whitelist. More text.

Here is an example of an exemption that acts upon an element (the string

wokeignore:rule=master

"master") of a URL. It is recommended to do this by using the standard reST

method of placing the link at the bottom of the page (or in a separate file):

This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,`

Here is an example of an exemption that acts upon an element (the string

"master") of a URL. It is recommended to do this by using the standard reST :none:`wokeignore:rule=master,`

method of placing the link at the bottom of the page (or in a separate file):

Signed-off-by: Peter Matulis <[email protected]>

ru-fu

Two more nitpicks, but otherwise it seems to work now. :)

ru-fu · 2024-01-03T17:35:28Z

.wordlist.txt

@@ -44,3 +44,4 @@ UI
 UUID
 VM
 YAML
+wokeignore


Not needed anymore.

ru-fu · 2024-01-03T17:36:49Z

help-woke.rst

+
+You can now refer to the label ``link definition_`` in the body of the text.
+
+Here :none:`wokeignore:rule=master,` is an example where a URL element contains the string "master":


Duplicate of line 35.

Signed-off-by: Peter Matulis <[email protected]>

ru-fu

Thanks!

ru-fu reviewed Dec 14, 2023

View reviewed changes

ru-fu reviewed Dec 15, 2023

View reviewed changes

ru-fu suggested changes Jan 2, 2024

View reviewed changes

ru-fu reviewed Jan 3, 2024

View reviewed changes

Peter Matulis added 8 commits January 3, 2024 12:08

Refactor out woke instructions

ddd2a3a

Signed-off-by: Peter Matulis <[email protected]>

Edits as per review

f773132

Signed-off-by: Peter Matulis <[email protected]>

Spelling

6c88e19

Signed-off-by: Peter Matulis <[email protected]>

Fix inclusive language check failure

1d2c761

Signed-off-by: Peter Matulis <[email protected]>

Fix spelling check failure

2773874

Signed-off-by: Peter Matulis <[email protected]>

Fix woke stuff

e17f3e0

Signed-off-by: Peter Matulis <[email protected]>

Fix more woke stuff

f264cb8

Signed-off-by: Peter Matulis <[email protected]>

Even more fixups

7553d1d

Signed-off-by: Peter Matulis <[email protected]>

pmatulis force-pushed the refactor-out-woke-instructions branch from 2988244 to 7553d1d Compare January 3, 2024 17:14

ru-fu reviewed Jan 3, 2024

View reviewed changes

Edits as per review

4749735

Signed-off-by: Peter Matulis <[email protected]>

ru-fu approved these changes Jan 4, 2024

View reviewed changes

ru-fu merged commit df2460d into canonical:main Jan 4, 2024
2 checks passed

pmatulis deleted the refactor-out-woke-instructions branch January 4, 2024 18:20

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor out woke instructions #158

Refactor out woke instructions #158

pmatulis commented Dec 13, 2023 •

edited

Loading

ru-fu left a comment

ru-fu Dec 14, 2023

pmatulis Dec 14, 2023

ru-fu Dec 14, 2023

ru-fu Dec 14, 2023

ru-fu Dec 14, 2023

pmatulis Dec 14, 2023

ru-fu Dec 14, 2023

ru-fu Dec 14, 2023

ru-fu left a comment

pmatulis commented Dec 15, 2023

ru-fu commented Jan 2, 2024

ru-fu Jan 2, 2024

ru-fu commented Jan 2, 2024

ru-fu left a comment

ru-fu Jan 3, 2024

ru-fu left a comment

ru-fu Jan 3, 2024

ru-fu Jan 3, 2024

ru-fu left a comment

	the line containing the word in question. This special comment is to include
	the line containing the word in question. This special comment must include

		Here is an example of an exemption that acts upon an element of a URL that is
		expressed using the link definition method (typically at the bottom of a file):

	Some circumstances may compel you to retain some non-inclusive words. In such
	Some circumstances might require you to use some non-inclusive words. In such


		You can now refer to the label ``link definition_`` in the body of the text.

		Here :none:`wokeignore:rule=master,` is an example where a URL element contains the string "master":

Refactor out woke instructions #158

Refactor out woke instructions #158

Conversation

pmatulis commented Dec 13, 2023 • edited Loading

ru-fu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ru-fu left a comment

Choose a reason for hiding this comment

pmatulis commented Dec 15, 2023

ru-fu commented Jan 2, 2024

Choose a reason for hiding this comment

ru-fu commented Jan 2, 2024

ru-fu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ru-fu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ru-fu left a comment

Choose a reason for hiding this comment

pmatulis commented Dec 13, 2023 •

edited

Loading