Link message symbols and message ids in the documentation - #11265
Draft
Pierre-Sassoulas wants to merge 6 commits into
Draft
Link message symbols and message ids in the documentation#11265Pierre-Sassoulas wants to merge 6 commits into
Pierre-Sassoulas wants to merge 6 commits into
Conversation
A message symbol like no-member, or an id like E1101, was plain text, so a reader who wanted to know what it means had to go and search for its page. Turn both into links to that page. Each link carries an explicit title, so the words on the page do not change. A bare ':ref:' would display the page title instead, which is 'symbol / msgid', and several places already write the msgid themselves or quote a symbol as an example of what a symbolic name looks like. Where an entry named the same message both ways, one of the two is now dropped: the id in 'E1310[bad-str-strip-call]' and the parenthesis in 'missing-raises-doc (W9006)' only repeated the link. The two ids in the duplicate-code entry are kept as literal text, because there they contrast the message with the report that shares its name. Symbols inside an inline literal are left alone: there they are almost always part of a command line or of a configuration snippet meant to be copied. Refs pylint-dev#10568
A checker is the class that runs; a message is what it reports. Nine changelog entries used 'checker' for a message symbol, and two of them for an option name. Linking the names made the mix-up visible: 'the duplicate-code checker' pointed at a message page. Say 'check' where the entry is about what is reported, and name the Similarities checker where the entry really is about the checker, as in the one that no longer runs when its message is disabled. Refs pylint-dev#10568
Those seven symbols and ids became names pylint knows again, so the changelog entries mentioning them can link to their page. One entry named old-style-class both by symbol and by id; the id is dropped, the link carries it. Refs pylint-dev#10568
Entries about the checker itself, rather than about the message it raises, can point at the checker's own section since pylint-dev#11263. Refs pylint-dev#10568
Pierre-Sassoulas
added
Documentation 📗
Skip news 🔇
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #11265 +/- ##
=======================================
Coverage 96.36% 96.36%
=======================================
Files 178 178
Lines 19953 19953
=======================================
Hits 19228 19228
Misses 725 725 🚀 New features to boost your workflow:
|
An entry that already named its symbol ended up saying it twice, once in prose and once as the id link that now displays the same word: 'The ``no-init`` (no-init) warning has been removed'. Keep the symbol, drop the id, and let the symbol carry the link. Where the entry named only the id, the link displays the symbol: an entry about a message reads better naming it than naming its number, and the number is on the page the link goes to. An entry about the numbering itself keeps its ids, unlinked. 'W0212 (method could be a function) has been reclassified as R0201' is about what the ids used to mean, and ids get recycled: W0212 is 'protected-access' today, and the E0705 of 'Demote try-except-raise from an error to a warning (E0705 -> W0706)' is 'bad-exception-cause', so those links sent the reader to a page about another message. The msg-template example and the 'disable-msg=W0402' pragma keep their id for the same reason: there the id is what the reader needs to type. Three sentences said something else once the id became a link: a message that was removed read as a fixed weirdness, 'not Missing docstring (...) warning' repeated the symbol, and quoting a link adds nothing. Refs pylint-dev#10568
A message page is titled 'symbol / msgid', so a bare ':ref:' to one displayed both in the middle of a sentence: 'For unittest assertions there is the similar redundant-unittest-assert / W0129 message'. Name the symbol explicitly, as the links added for the entries that spell it out do. Anchors that document something else keep their own title: a section or the option list reads better named by its title than by its anchor. Refs pylint-dev#10568
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Type of Changes
Description
A bare message symbol like no-member was plain text, so a reader who wanted to know what it means had to go and search for its page. Turn the symbols the documentation and the changelogs mention into links to that page.
Symbols inside an inline literal are left alone: there they are almost always part of a command line or of a configuration snippet meant to be copied.
Refs #10568