gh-96414: Inline code examples in sqlite3 docs #96442
Conversation
|
@CAM-Gerlach, do you think this is worth it? IMO, the benefits of inlining the examples (being able to doctest them, etc.) outweigh the churn. I don't expect you to review each line here; I've just moved a lot of lines :) |
There was a problem hiding this comment.
IMO, Diataxis stresses that examples given must work and work reliably, especially for tutorials. So, given this just requires moving them around, actually testing them would seem to be worth it.
However, just to make sure, is the doctest CI check actually correctly failing if a doctest fails? Perhaps I'm mistaken, but at least per my recollection of a discussion on the Docs Community Discord, doctests failing doesn't actually fail the build, it just produces messages/output—but perhaps I'm entirely mistaken on that, and its just referring to warnings or something.
I did have some trivial comments regarding consistent SQL code style, given you mentioned that conforming that was in scope for this PR.
Yes. I learned that when I applied doctests to the tutorial. Several of the examples had inconsistencies that made the code and thus the doctest fail. |
Thanks! :) |
|
Thanks @erlend-aasland for the PR 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11. |
(cherry picked from commit f7e7bf1) Co-authored-by: Erlend E. Aasland <erlend.aasland@protonmail.com>
|
Sorry, @erlend-aasland, I could not cleanly backport this to |
|
GH-96452 is a backport of this pull request to the 3.11 branch. |
|
GH-96453 is a backport of this pull request to the 3.10 branch. |
This PR inlines all sqlite3 doc examples into
Doc/library/sqlite3.rst.Except from adjusting the SQL style, the examples are mostly kept as they are;
some of them work well, others can be improved in later PRs.