Skip to content

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

Merged
erlend-aasland merged 1 commit into
python:mainfrom
CAM-Gerlach:sqlite-fix-bad-point-reference
Aug 19, 2022
Merged

Doc: Fix ref warnings for Point class in sqlite3 & make consistant#96095
erlend-aasland merged 1 commit into
python:mainfrom
CAM-Gerlach:sqlite-fix-bad-point-reference

Conversation

@CAM-Gerlach

@CAM-Gerlach CAM-Gerlach commented Aug 19, 2022

Copy link
Copy Markdown
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.

@bedevere-bot bedevere-bot added docs Documentation in the Doc dir skip news awaiting review labels Aug 19, 2022
@CAM-Gerlach CAM-Gerlach mentioned this pull request Aug 19, 2022
Closed
ezio-melotti
ezio-melotti reviewed Aug 19, 2022
View reviewed changes

@ezio-melotti ezio-melotti left a comment

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.

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

CAM-Gerlach commented Aug 19, 2022 •
edited
Loading

Copy link
Copy Markdown
Member Author

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

ezio-melotti commented Aug 19, 2022

Copy link
Copy Markdown
Member

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

@erlend-aasland

erlend-aasland commented Aug 19, 2022

Copy link
Copy Markdown
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

miss-islington commented Aug 19, 2022

Copy link
Copy Markdown
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

bedevere-bot commented Aug 19, 2022

Copy link
Copy Markdown

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

bedevere-bot commented Aug 19, 2022

Copy link
Copy Markdown

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
@CAM-Gerlach @miss-islington
Doc: Use consistent markup for example Point class in sqlite3 (python…
35ecfe7 
…GH-96095)

(cherry picked from commit 303ef09)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Aug 19, 2022
@CAM-Gerlach @miss-islington
Doc: Use consistent markup for example Point class in sqlite3 (python…
0d74f27 
…GH-96095)

(cherry picked from commit 303ef09)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington added a commit that referenced this pull request Aug 19, 2022
@miss-islington @CAM-Gerlach
Doc: Use consistent markup for example Point class in sqlite3 (GH-96095)
f21d7e5 
(cherry picked from commit 303ef09)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
miss-islington added a commit that referenced this pull request Aug 19, 2022
@miss-islington @CAM-Gerlach
Doc: Use consistent markup for example Point class in sqlite3 (GH-96095)
d52834d 
(cherry picked from commit 303ef09)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ezio-melotti ezio-melotti ezio-melotti left review comments
@berkerpeksag berkerpeksag Awaiting requested review from berkerpeksag
@erlend-aasland erlend-aasland Awaiting requested review from erlend-aasland erlend-aasland is a code owner

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@CAM-Gerlach @ezio-melotti @erlend-aasland @miss-islington @bedevere-bot