Repository navigation
Improve the sqlite3 reference #95273
Description
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...:
- 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
sqlite3docs #30660 - bpo-45677: Reword first section of
sqlite3docs #29326 - bpo-45335: Add note to
sqlite3docs about "timestamp" converter #29200 - bpo-45608: Document missing
sqlite3DB-API attributes and methods #29219 - bpo-45089: Improve
sqlite3trace 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:
- 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:
- 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.
Footnotes
-
There have been too many PRs to list; some of them were done before Diataxis was even discussed. ↩
Metadata
Metadata
Assignees
Projects
- Status
Activity
[-]Normalise wording of sqlite3 function and method docs[/-][+]Normalise sqlite3 reference doc wording[/+]pythongh-95273: Normalise sqlite3 reference wording
[-]Normalise sqlite3 reference doc wording[/-][+]Improve the sqlite3 reference[/+]gh-95273: Normalise sqlite3 reference wording (#95274)
pythongh-95273: Normalise sqlite3 reference wording (pythonGH-95274)
[3.10] pythongh-95273: Normalise sqlite3 reference wording (pythonGH-…
gh-95273: Normalise sqlite3 reference wording (GH-95274)
[3.10] gh-95273: Normalise sqlite3 reference wording (GH-95274) (#95330)
pythongh-95273: Move sqlite3 executemany examples from reference to t…
pythongh-95273: Improve sqlite3 class descriptions
pythongh-95273: Condense sqlite3 executescript example
51 remaining items
[3.11] pythongh-95273: Reorganize sqlite3 doc module level funcs and …
[3.10] pythongh-95273: Reorganize sqlite3 doc module level funcs and …
[3.10] gh-95273: Reorganize sqlite3 doc module level funcs and vars (G…
[3.11] gh-95273: Reorganize sqlite3 doc module level funcs and vars (G…
pythongh-95273: Improve sqlite3.complete_statement docs
pythongh-95273: Improve documented return values and exceptions raise…
pythongh-95273: Reorganize sqlite3 doc module level funcs and vars (p…
gh-95273: Improve sqlite3.complete_statement docs (#95840)
[3.11] pythongh-95273: Improve sqlite3.complete_statement docs (pytho…
[3.10] pythongh-95273: Improve sqlite3.complete_statement docs (pytho…
[3.11] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#…
[3.10] gh-95273: Improve sqlite3.complete_statement docs (GH-95840) (#…
erlend-aasland commentedon Aug 18, 2022
I'm going to close this issue:
Further work can be done either without PRs (moving a section, minor rewordings, etc.) or with better targeted issues.
erlend-aasland commentedon Aug 18, 2022
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!