data-apis
docs: format RFC 2119 keywords
aims to address https://github.com/data-apis/array-api/issues/397, https://github.com/data-apis/array-api/issues/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.
$ 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
I noticed that gh-801 tries doing the same thing. Could you compare and recommend which approach to use?
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.
IMO, the approach in this PR is preferred when compared to https://github.com/data-apis/array-api/pull/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.
OK, reverted all changes to spec/, so that only files in src/array_api_stubs/_draft/* are affected.