Description

erlend-aasland

opened on Jul 26, 2022

Issue body actions

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 far¹ have focused on...:

• Be accurate
• Do nothing but describe; making the wording more to the point

Previous work over the last few years

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

• Update sqlite3 docs with positional-only and keyword-only symbols #94630
• Document all parameters of all sqlite3 functions/methods #95235
• Document all parameters of all sqlite3 functions/methods #95235
• gh-81040: Improve sqlite3.Cursor.rowcount docs #94940
• Document sqlite3.PrepareProtocol #94321
• Doc: Add explicit parameter list to sqlite3.connect #94628
• Improve clarity of sqlite3 transaction handling docs #94017
• gh-61162: Clarify sqlite3 connection context manager docs #93890
• Improve docs/docstrings of sqlite3 commit()/rollback() and close() #93925
• sqlite3 signature discrepancies between documentation and implementation #87260
• [doc] Complete the sqlite3 exception documentation #89018
• sqlite3: Connection.create_collation() documentation inaccuracies #92780
• [Doc] sqlite3 Cursor.execute() return value is unspecified #90923
• bpo-46402: Promote SQLite URI tricks in sqlite3 docs #30660
• bpo-45677: Reword first section of sqlite3 docs #29326
• bpo-45335: Add note to sqlite3 docs about "timestamp" converter #29200
• bpo-45608: Document missing sqlite3 DB-API attributes and methods #29219
• bpo-45089: Improve sqlite3 trace callback docs #28238
• bpo-30593: Document that sqlite3.Cursor.executescript disregards isolation_level #26220
• bpo-20364: Improve sqlite3 placeholder docs #25003
• bpo-38413: Improve documentation of sqlite3 module #23159
• bpo-42755: Fix sqlite3.Connection.backup docs #23965
• consistency: Doc: normalise pre-acronym determiners #31772
• consistency: bpo-43396: normalise naming in sqlite3 doc examples #24746

There are remaining issues, though:

• Be accurate:
  • gh-95273: Improve sqlite3 class descriptions #95379
  • gh-95273: Clarify when the sqlite_* attributes are added to sqlite3 exceptions #95523
  • gh-95273: Improve documented return values and exceptions raised for sqlite3 class methods #95530
• 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:
  • gh-95273: Normalise sqlite3 reference wording #95274
  • gh-95273: Align sqlite3 const refs with the devguide #95525
  • Remove duplicate links
• 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:
  • Consistently group attributes and methods
  • gh-95273: Reorganize sqlite3 doc module level funcs and vars #95626
  • gh-95273: Relocate sqlite3 enable load extension note #95430
  • Align wording in function and method docstrings with documentation
• Do nothing but describe: Avoid digressions and discussions, or even better, extract them to separate sections. Remove and or simplify examples.
  • gh-95273: Move sqlite3 executemany examples from reference to tutorial #95351
  • gh-95273: Condense sqlite3 executescript example #95383
  • gh-95273: Improve sqlite3.complete_statement docs #95840

Footnotes

1. There have been too many PRs to list; some of them were done before Diataxis was even discussed. ↩

Reacted by C.A.M. Gerlach

Activity

1. erlend-aasland

   self-assigned this

   on Jul 26, 2022
2. erlend-aasland

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   triagedThe issue has been accepted as valid by a triager.The issue has been accepted as valid by a triager.

   on Jul 26, 2022
3. erlend-aasland

   changed the title [-]Normalise wording of sqlite3 function and method docs[/-] [+]Normalise sqlite3 reference doc wording[/+] on Jul 26, 2022
4. erlend-aasland

   added a commit that references this issue on Jul 26, 2022

   pythongh-95273: Normalise sqlite3 reference wording

   4130c33
5. erlend-aasland

   moved this from TODO: Docs to In Progress in sqlite3 issueson Jul 26, 2022
6. erlend-aasland

   changed the title [-]Normalise sqlite3 reference doc wording[/-] [+]Improve the sqlite3 reference[/+] on Jul 27, 2022
7. erlend-aasland

   added a commit that references this issue on Jul 27, 2022

   gh-95273: Normalise sqlite3 reference wording (#95274)

   2361908
8. miss-islington

   added a commit that references this issue on Jul 27, 2022

   pythongh-95273: Normalise sqlite3 reference wording (pythonGH-95274)

   540833f
9. erlend-aasland

   added a commit that references this issue on Jul 27, 2022

   [3.10] pythongh-95273: Normalise sqlite3 reference wording (pythonGH-…

   056afa8
10. miss-islington

    added a commit that references this issue on Jul 27, 2022

    gh-95273: Normalise sqlite3 reference wording (GH-95274)

    e14c4d5
11. erlend-aasland

    added 4 commits that reference this issue on Jul 27, 2022

    [3.10] gh-95273: Normalise sqlite3 reference wording (GH-95274) (#95330)

    2ef7a72

    pythongh-95273: Move sqlite3 executemany examples from reference to t…

    6a5cb61

    pythongh-95273: Improve sqlite3 class descriptions

    4e72a1a

    pythongh-95273: Condense sqlite3 executescript example

    f4f1042
12. 51 remaining items
13. erlend-aasland

    added 5 commits that reference this issue on Aug 8, 2022

    [3.11] pythongh-95273: Reorganize sqlite3 doc module level funcs and …

    2e1a1c6

    [3.10] pythongh-95273: Reorganize sqlite3 doc module level funcs and …

    5688dc2

    [3.10] gh-95273: Reorganize sqlite3 doc module level funcs and vars (G…

    49e505c

    [3.11] gh-95273: Reorganize sqlite3 doc module level funcs and vars (G…

    d7a6a97

    pythongh-95273: Improve sqlite3.complete_statement docs

    2d3b7f1
14. iritkatriel

    added 2 commits that reference this issue on Aug 11, 2022

    pythongh-95273: Improve documented return values and exceptions raise…

    26026fe

    pythongh-95273: Reorganize sqlite3 doc module level funcs and vars (p…

    37d7645
15. erlend-aasland

    added 5 commits that reference this issue on Aug 11, 2022

    gh-95273: Improve sqlite3.complete_statement docs (#95840)

    e6623e7

    [3.11] pythongh-95273: Improve sqlite3.complete_statement docs (pytho…

    ed35c22

    [3.10] pythongh-95273: Improve sqlite3.complete_statement docs (pytho…

    49443c0

    [3.11] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#…

    bd86e09

    [3.10] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#…

    75299dc
16. erlend-aasland commented on Aug 18, 2022

    

    erlend-aasland

    on Aug 18, 2022

    ContributorAuthor

    More actions

    I'm going to close this issue:

    • it is close to impossible to say when such a meta-issue can be closed as it's goal is a moving target
    • most of the issues pointed out have been fixed

    Further work can be done either without PRs (moving a section, minor rewordings, etc.) or with better targeted issues.
17. erlend-aasland

    closed this as completedon Aug 18, 2022
18. erlend-aasland commented on Aug 18, 2022

    

    erlend-aasland

    on Aug 18, 2022

    ContributorAuthor

    More actions

    A big thanks to Alex, CAM, and Ezio, who have been helping out by improving the quality of the changes considerably. Thank you so much!

    Reacted by Ezio Melotti

    Reacted by Alex Waygood

    Reacted by Alex Waygood

Issue actions