Skip to content

Doc: Fix ref warnings for Point class in sqlite3 & make consistant #96095

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

Merged

Conversation

CAM-Gerlach
Copy link
Member

After all of @erlend-aasland 's work in the sqlite3 module docs, there are only a few broken references (causing warnings) left. Following our guidance established earlier, this fixes :class: references to the example Point class to be non-resolved (!), and also converts a literal reference to a non-resolved :class: for syntactic, semantic and formatting consistency.

This leaves only warnings about the missing SQLITE_* module-level constants that are currently not explicitly documented (like sqlite.PrepareProtocol), but I'll open a separate issue for that, since the fix is somewhat less trivial.

Copy link
Member

@ezio-melotti ezio-melotti left a comment

Choose a reason for hiding this comment

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

Are there any difference in the rendering of the output or other reasons that make :class:`!Point` preferable to just ``Point``?
If you consider it simply a variable, then ``Point`` would be appropriate, and makes the source easier to read/write.

@CAM-Gerlach
Copy link
Member Author

CAM-Gerlach commented Aug 19, 2022

Actually, it does render differently:

``Point``

image

vs. :class:`!Point`

image

I don't have a strong preference; I could see an argument for it either way. On one hand, Point does represent a class, just one defined in the examples rather than in the module itself, so from that angle it would seem consistent to treat it like other class names, just unresolved, rather than as a variable. On the other, it could be considered example code snippet, since it isn't actually defined in the module itself, given the primarily purpose of the roles is for cross referencing.

@ezio-melotti @erlend-aasland what do you think? We can go with whatever you agree is best here, and presumably document that for the future at some point along with the rest of python/docs-community#52

@ezio-melotti
Copy link
Member

In this case I prefer ``...``.

@erlend-aasland
Copy link
Contributor

Since we already use (broken) :class: refs here, I'm fine with explicitly removing the links, and making the formatting consistent.

@erlend-aasland erlend-aasland merged commit 303ef09 into python:main Aug 19, 2022
@miss-islington
Copy link
Contributor

Thanks @CAM-Gerlach for the PR, and @erlend-aasland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

@bedevere-bot
Copy link

GH-96113 is a backport of this pull request to the 3.11 branch.

@bedevere-bot bedevere-bot removed needs backport to 3.11 only security fixes needs backport to 3.10 only security fixes labels Aug 19, 2022
@bedevere-bot
Copy link

GH-96114 is a backport of this pull request to the 3.10 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 19, 2022
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 19, 2022
miss-islington added a commit that referenced this pull request Aug 19, 2022
miss-islington added a commit that referenced this pull request Aug 19, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir skip issue skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants