docs: format RFC 2119 keywords - #872
Conversation
Sorry, something went wrong.
|
I noticed that gh-801 tries doing the same thing. Could you compare and recommend which approach to use? |
Sorry, something went wrong.
|
Ah, indeed. gh-801 looks more polished of course. Can't see what the rendered docs look like since the link has expired and CircleCI needs a kick from somebody with the right permissions (does not seem to react to my prods). Assuming the rendered docs in gh-801 are what we want them to be, the choice boils down to whether we prefer to maintain a dedicated Sphinx extension (gh-801) or run sed once (this PR) and remember to bold/italicize the RFC words in new prose/docstrings. My personal preference would be for the latter, but I'm not the main writer here. |
Sorry, something went wrong.
|
IMO, the approach in this PR is preferred when compared to #801. The main issue which I raised there is that changes should actually be constrained to normative content. At least to start, I recommend only modifying the use of should and must in the stubs files. In design topics, e.g., we are not as careful with our language. |
Sorry, something went wrong.
|
OK, reverted all changes to spec/, so that only files in src/array_api_stubs/_draft/* are affected. |
Sorry, something went wrong.
$ sed -E -i "/not/! s/must/\*must\*/g" ./*.rst $ sed -E -i "s/must not/\*must not\*/g" ./*.rst $ sed -E -i "/not/! s/should/\*should\*/g" ./*.rst etc
aims to address #397, #796
typeset RFC 2119 magic keywords (should/must/must not) in lowercase italics; the preference in gh-397 seems to avoid ALLCAPS.
No specific preference for italics either, can change to boldface---did not do it just yet because boldface is already in use in phrases like The full **singular value decomposition** of an :math:m \times n matrix ...
Either way, if there's a strong preference for boldface or other, it's easy to change, just slightly tweak the sed stanzas under the fold.
Note that I only spot-checked the diff, so it's possible that the search-and-replace changed too much.
Details$ sed -E -i "/not/! s/must/\*must\*/g" ./*.rst $ sed -E -i "s/must not/\*must not\*/g" ./*.rst $ sed -E -i "/not/! s/should/\*should\*/g" ./*.rst