Skip to content

docs: format RFC 2119 keywords #872

New issue

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

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

Already on GitHub? # to your account

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

Conversation

ev-br
Copy link
Member

@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
Member 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
Member 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
@kgryte kgryte modified the milestones: v2024, v2025 Jan 23, 2025
# for free to join this conversation on GitHub. Already have an account? # 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