FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Doc: remove redundant refs in sqlite3 docs by erlend-aasland · Pull Request #94667 · python/cpython · GitHub

/ cpython Public

Doc: remove redundant refs in sqlite3 docs - #94667

Closed
erlend-aasland wants to merge 1 commit into
python:mainfrom
erlend-aasland:sqlite-remove-unneeded-refs
Closed

Doc: remove redundant refs in sqlite3 docs#94667
erlend-aasland wants to merge 1 commit into
python:mainfrom
erlend-aasland:sqlite-remove-unneeded-refs

Conversation

erlend-aasland commented Jul 7, 2022
edited
Loading

Copy link
Copy Markdown
Contributor

Each type can be ref'ed using the :class: directive; there is no reason to provide duplicate :ref:'s.

Copy link
Copy Markdown
Contributor Author

See #94620 (comment)

Copy link
Copy Markdown
Contributor Author

FTR, I checked that there is no existing ref's to these in other parts of the docs (NEWS items, What's New, etc.)

CAM-Gerlach left a comment
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Just to note, perhaps a little pedantic but the ref targets aren't completely syntactically and semantically redundant—their targets are the sections, while the :class: directive target is the class item, which can make both a syntactic and semantic difference in some contexts. If content outside the class directive, such as an introduction, examples, or other classes/objects is added to the section, then the class directive is not practically equivalent, especially so in practice if the content is added above the linked class, or in a different scope.

In this case, the only current examples of this are a versionadded directive above the Blob class, and some rather lengthy examples below the Row class (which besides being a little lengthy for the context, are somewhat confusing, since it references "the example given above", but is unclear which of the many examples this is—evidently the one in the document introduction). However, additional such material could be added at any point in the future, in which case the refs should presumably be re-added.

Whether they are worthwhile to keep, though, is up to you.

Some other more minor notes:

  • If the class is ever renamed/replaced by another in the same section, class refs will break, wheres section refs will not. That's pretty unlikely, though.
  • While no internal links may be using it, it is theoretically possible that external links might, if there was a previous :ref: and they copied the link from that ref, (or manually did so, for a more robust link than relying on the section name not to change). But again, that's pretty unlikely.

Copy link
Copy Markdown
Contributor Author

Nah, there's more important stuff to do with the sqlite3 docs than something like this. Churn for little value. I'm closing the PR. Thanks!

erlend-aasland deleted the sqlite-remove-unneeded-refs branch July 7, 2022 23:10

Copy link
Copy Markdown
Member

Probably spent too much time writing that comment too myself 😅

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants


Back | FazBrowse Home | New Git URL