Skip to content
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

Jump to bottom

Improve the sqlite3 reference #95273

Open
5 tasks
erlend-aasland opened this issue Jul 26, 2022 · 0 comments · Fixed by #95523, #95379, #95274, #95430 or #95351
Open
5 tasks

Improve the sqlite3 reference #95273

erlend-aasland opened this issue Jul 26, 2022 · 0 comments · Fixed by #95523, #95379, #95274, #95430 or #95351
Assignees
@erlend-aasland
Labels
docs Documentation in the Doc dir triaged The issue has been accepted as valid by a triager.

Comments

@erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Jul 26, 2022 •
edited

Improve the sqlite3 reference, using Diataxis as a guideline. A lot of work has already been done here, with great help from Alex Waygood and CAM Gerlach. PRs so far1 have focused on...:

Previous work over the last few years

Both of these have been improved greatly by the following issues and PRs, amongst others:

There are remaining issues, though:

  • Be accurate:
  • Be consistent: Most of the reference docs for sqlite3 functions and methods use the imperative mood. Some of the methods use other wordings. Suggesting to normalise, and use the imperative mood across the reference section.
    Improved with:
  • Respect the structure of the machinery: Arrange the sections of reference to follow the architecture of the module. This is pretty good already, but I believe we may benefit from some adjustments, in particular:
  • Do nothing but describe: Avoid digressions and discussions, or even better, extract them to separate sections. Remove and or simplify examples.

Footnotes

  1. There have been too many PRs to list; some of them were done before Diataxis was even discussed. ↩
@erlend-aasland erlend-aasland self-assigned this Jul 26, 2022
@erlend-aasland erlend-aasland added docs Documentation in the Doc dir triaged The issue has been accepted as valid by a triager. labels Jul 26, 2022
@erlend-aasland erlend-aasland changed the title Normalise wording of sqlite3 function and method docs Normalise sqlite3 reference doc wording Jul 26, 2022
@bedevere-bot bedevere-bot mentioned this issue Jul 26, 2022
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 26, 2022
@erlend-aasland
pythongh-95273: Normalise sqlite3 reference wording
4130c33
@erlend-aasland erlend-aasland changed the title Normalise sqlite3 reference doc wording Improve the sqlite3 reference Jul 27, 2022
erlend-aasland added a commit that referenced this issue Jul 27, 2022
@erlend-aasland @AlexWaygood @CAM-Gerlach
gh-95273: Normalise sqlite3 reference wording (#95274)
2361908 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
@bedevere-bot bedevere-bot mentioned this issue Jul 27, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 27, 2022
@erlend-aasland @miss-islington
pythongh-95273: Normalise sqlite3 reference wording (pythonGH-95274)
540833f 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit 2361908)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 27, 2022
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 27, 2022
@erlend-aasland
[3.10] pythongh-95273: Normalise sqlite3 reference wording (pythonGH-…
056afa8 
…95274)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 2361908)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
miss-islington added a commit that referenced this issue Jul 27, 2022
@miss-islington @erlend-aasland
gh-95273: Normalise sqlite3 reference wording (GH-95274)
e14c4d5 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
(cherry picked from commit 2361908)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
erlend-aasland added a commit that referenced this issue Jul 27, 2022
@erlend-aasland
[3.10] gh-95273: Normalise sqlite3 reference wording (GH-95274) (#95330)
2ef7a72 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 2361908)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 27, 2022
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 27, 2022
@erlend-aasland
pythongh-95273: Move sqlite3 executemany examples from reference to t…
6a5cb61 
…utorial
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 28, 2022
@erlend-aasland
pythongh-95273: Improve sqlite3 class descriptions
4e72a1a
This was referenced Jul 28, 2022
Merged
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Jul 28, 2022
@erlend-aasland
pythongh-95273: Condense sqlite3 executescript example
f4f1042
erlend-aasland added a commit that referenced this issue Jul 29, 2022
@erlend-aasland
gh-95273: Condense sqlite3 executescript example (#95383)
e9c8de6
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 29, 2022
@erlend-aasland @miss-islington
pythongh-95273: Condense sqlite3 executescript example (pythonGH-95383)
08d7e30 
(cherry picked from commit e9c8de6)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 29, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 29, 2022
@erlend-aasland @miss-islington
pythongh-95273: Condense sqlite3 executescript example (pythonGH-95383)
61ac35d 
(cherry picked from commit e9c8de6)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 29, 2022
Merged
erlend-aasland added a commit that referenced this issue Jul 29, 2022
@erlend-aasland
gh-95273: Move sqlite3 executemany examples from reference to tutorial (
f0bf795 
#95351)
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 29, 2022
@erlend-aasland @miss-islington
pythongh-95273: Move sqlite3 executemany examples from reference to t…
946ab9c 
…utorial (pythonGH-95351)

(cherry picked from commit f0bf795)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 29, 2022
Merged
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Jul 29, 2022
@erlend-aasland @miss-islington
pythongh-95273: Move sqlite3 executemany examples from reference to t…
5b1044d 
…utorial (pythonGH-95351)

(cherry picked from commit f0bf795)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
@bedevere-bot bedevere-bot mentioned this issue Jul 29, 2022
Merged
This was referenced Aug 1, 2022
Merged
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 1, 2022
@erlend-aasland
pythongh-95273: Improve return values and exceptions raised for sqlit…
f9dc7d6 
…e3 class methods
@erlend-aasland erlend-aasland linked a pull request Aug 1, 2022 that will close this issue
gh-95273: Improve documented return values and exceptions raised for sqlite3 class methods #95530
Merged
@bedevere-bot bedevere-bot mentioned this issue Aug 3, 2022
Merged
erlend-aasland added a commit that referenced this issue Aug 3, 2022
@erlend-aasland
gh-95273: Align sqlite3 const doc refs with the devguide recommendati…
4d02572 
…ons (#95525)
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Aug 3, 2022
@erlend-aasland @miss-islington
pythongh-95273: Align sqlite3 const doc refs with the devguide recomm…
18eaa5c 
…endations (pythonGH-95525)

(cherry picked from commit 4d02572)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
miss-islington added a commit that referenced this issue Aug 3, 2022
@miss-islington @erlend-aasland
gh-95273: Align sqlite3 const doc refs with the devguide recommendati…
8d09626 
…ons (GH-95525)

(cherry picked from commit 4d02572)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 3, 2022
@erlend-aasland
[3.10] pythongh-95273: Align sqlite3 const doc refs with the devguide…
3c69446 
… recommendations (pythonGH-95525).

(cherry picked from commit 4d02572)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 3, 2022
Merged
erlend-aasland added a commit that referenced this issue Aug 3, 2022
@erlend-aasland
[3.10] gh-95273: Align sqlite3 const doc refs with the devguide recom…
ac005ea 
…mendations (GH-95525). (#95618)

(cherry picked from commit 4d02572)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 3, 2022
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 3, 2022
@erlend-aasland
pythongh-95273: Re-organize sqlite3 doc module level funcs and attrs
7452815 
Put module level functions before module level attributes, and (mostly)
sort them alphabetically.  This makes sqlite3.connect() the first
encounter in the sqlite3 reference.
@erlend-aasland erlend-aasland linked a pull request Aug 3, 2022 that will close this issue
gh-95273: Align sqlite3 const refs with the devguide #95525
Merged
erlend-aasland added a commit that referenced this issue Aug 4, 2022
@erlend-aasland @ezio-melotti @AlexWaygood
gh-95273: Improve documented return values and exceptions raised for …
12d92c7 
…sqlite3 class methods (#95530)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 4, 2022
Merged
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 4, 2022
@erlend-aasland
[3.11] pythongh-95273: Improve documented return values and exception…
f86a981 
…s raised for sqlite3 class methods (pythonGH-95530)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 12d92c7)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 4, 2022
@erlend-aasland
[3.10] pythongh-95273: Improve documented return values and exception…
1e6ceaf 
…s raised for sqlite3 class methods (pythonGH-95530)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>.
(cherry picked from commit 12d92c7)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 4, 2022
Merged
@erlend-aasland erlend-aasland reopened this Aug 4, 2022
erlend-aasland added a commit that referenced this issue Aug 4, 2022
@erlend-aasland
[3.11] gh-95273: Improve documented return values and exceptions rais…
c9986be 
…ed for sqlite3 class methods (GH-95530) (#95673)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
(cherry picked from commit 12d92c7)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
erlend-aasland added a commit that referenced this issue Aug 4, 2022
@erlend-aasland
[3.10] gh-95273: Improve documented return values and exceptions rais…
4a204c1 
…ed for sqlite3 class methods (GH-95530) (#95674)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>.
(cherry picked from commit 12d92c7)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@protonmail.com>
erlend-aasland added a commit that referenced this issue Aug 8, 2022
@erlend-aasland @ezio-melotti @CAM-Gerlach
gh-95273: Reorganize sqlite3 doc module level funcs and vars (#95626)
41c939c 
Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 8, 2022
@erlend-aasland
[3.11] pythongh-95273: Reorganize sqlite3 doc module level funcs and …
2e1a1c6 
…vars (pythonGH-95626)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 41c939c)

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 8, 2022
Open
erlend-aasland added a commit to erlend-aasland/cpython that referenced this issue Aug 8, 2022
@erlend-aasland
[3.10] pythongh-95273: Reorganize sqlite3 doc module level funcs and …
5688dc2 
…vars (pythonGH-95626)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 41c939c)

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
@bedevere-bot bedevere-bot mentioned this issue Aug 8, 2022
Merged
erlend-aasland added a commit that referenced this issue Aug 8, 2022
@erlend-aasland
[3.10] gh-95273: Reorganize sqlite3 doc module level funcs and vars (G…
49e505c 
…H-95626) (#95803)

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>
Co-authored-by: CAM Gerlach <CAM.Gerlach@Gerlach.CAM>.
(cherry picked from commit 41c939c)

Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@erlend-aasland erlend-aasland

Labels
docs Documentation in the Doc dir triaged The issue has been accepted as valid by a triager.
Projects
sqlite3 issues
Status: Done
Milestone
No milestone
1 participant
@erlend-aasland