Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: format RFC 2119 keywords #872

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Conversation

ev-br
Copy link

@ev-br ev-br commented Dec 10, 2024

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.

    $ 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

@ev-br ev-br added the Document Formatting Document formatting or styling. label Dec 10, 2024
@kgryte kgryte added this to the v2024 milestone Dec 11, 2024
@rgommers
Copy link
Member

I noticed that gh-801 tries doing the same thing. Could you compare and recommend which approach to use?

@ev-br
Copy link
Author

ev-br commented Dec 11, 2024

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.

@kgryte kgryte changed the title format RFC 2119 keywords docs: format RFC 2119 keywords Dec 12, 2024
@kgryte
Copy link
Contributor

kgryte commented Dec 12, 2024

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.

@kgryte kgryte added the Needs Changes Pull request which needs changes before being merged. label Dec 12, 2024
@ev-br
Copy link
Author

ev-br commented Dec 12, 2024

OK, reverted all changes to spec/, so that only files in src/array_api_stubs/_draft/* are affected.

@kgryte kgryte added Needs Review Pull request which needs review. and removed Needs Changes Pull request which needs changes before being merged. labels Dec 12, 2024
$ 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Document Formatting Document formatting or styling. Needs Review Pull request which needs review.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants