Improve the sqlite3 reference

[erlend-aasland]

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. ↩

[erlend-aasland]

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.

[erlend-aasland]

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!