Refactor out woke instructions

canonical / sphinx-docs-starter-pack

A documentation starter-pack

https://canonical-starter-pack.readthedocs-hosted.com/

Other

15 stars 37 forks source link

Refactor out woke instructions #158

Closed pmatulis closed 8 months ago

pmatulis commented 9 months ago

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:

pmatulis commented 9 months ago

Did I miss something?

ru-fu commented 8 months ago

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 commented 8 months ago

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

When we merge https://github.com/canonical/canonical-sphinx-extensions/pull/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.