Restructure the sqlite3 docs table-of-contents

[erlend-aasland]

The current docs are laid out more or less like this:

• short introduction
• relatively short tutorial
• reference
• how-to's/guides and some in-depth explanations

Suggesting to make the following improvements:

• add top-level headings for:
  • introduction
  • tutorial
  • reference
  • guides
  • concepts
• reorder sections according to the new ToC
• add anchors for each top-level heading

Implemented by (all backported to 3.11 and 3.10):

• gh-94635: Add sqlite3 'Introduction' and 'Tutorial' doc headings #95269
• gh-94635: Add Reference, How-to, and Concepts headings to sqlite3 docs #94636
• gh-94635: Fixup sqlite3 'Introduction' seealso note #95751
• gh-94635: Remove sqlite3 doc introduction heading #96089
• gh-94635: Normalise sqlite3 doc headings #94677 (closed, as it was implemented by other PRs)
• gh-94635: Frame sqlite3 how-to headings as such & move default adapters to Reference #96136

[erlend-aasland]

cc. @CAM-Gerlach #diataxis

[erlend-aasland]

• introduction
• tutorial
• reference
• guides
• concepts

Maybe it is better to swap Concepts and Guides:

• introduction
• tutorial
• reference
• concepts
• guides

[rhettinger]

FWIW, I teach sqlite3 directly from the current docs. They are VERY useful as-is.

I would like to know what problem is being solved here. From what I can tell, no user has ever had issues with the current arrangement.

[erlend-aasland]

FWIW, I teach sqlite3 directly from the current docs. They are VERY useful as-is.

Thanks!

I would like to know what problem is being solved here.

The top-level structure is flat. I'm suggesting to organise the sections under headings:

Current layout

Table of Contents

sqlite3 — DB-API 2.0 interface for SQLite databases

• Module functions and constants
• Connection Objects
• Cursor Objects
• Row Objects
• Blob Objects
• Exceptions
• SQLite and Python types
  • Introduction
  • Using adapters to store custom Python types in SQLite databases
    • Letting your object adapt itself
    • Registering an adapter callable
  • Converting SQLite values to custom Python types
  • Default adapters and converters
  • Adapter and Converter Recipes
• Controlling Transactions
• Using sqlite3 efficiently
  • Using shortcut methods
  • Accessing columns by name instead of by index
  • Using the connection as a context manager

After this PR

Table of Contents

sqlite3 — DB-API 2.0 interface for SQLite databases

• Introduction
• Tutorial
• Reference
  • Module functions and constants
  • Connection Objects
  • Cursor Objects
  • Row Objects
  • Blob Objects
  • Exceptions
• Guides
  • Using adapters to store custom Python types in SQLite databases
    • Letting your object adapt itself
    • Registering an adapter callable
  • Converting SQLite values to custom Python types
  • Adapter and Converter Recipes
    • Default adapters and converters
  • Using shortcut methods
  • Accessing columns by name instead of by index
  • Using the connection as a context manager
• Concepts
  • SQLite and Python types
  • Controlling Transactions

[erlend-aasland]

From what I can tell, no user has ever had issues with the current arrangement.

As I view it, this is a weak argument for keeping things as they are. There can be room for improvement, both in docs and code, even though no-one has taken the steps to create a ticket on the bug tracker.

[CAM-Gerlach]

Maybe it is better to swap Concepts and Guides:

At least per Diataxis, the most natural flow would have Explanations ("Concepts") last, since they are higher-level discussions of less urgent immediacy to most users...though, at least one of the "Concepts" subsections doesn't quite fit the "Explanation" mold, as discussed on the PR, and phrasing them as "Concepts" conveys more primacy than "Explanations".

FWIW, I teach sqlite3 directly from the current docs. They are VERY useful as-is.

Given your perspective, any additional details you could provide would be quite helpful. Are you referring to useful to yourself as an instructor? Or to your students—and if so, it would be helpful to know how you're evaluating that? Are they being used as a tutorial, reference, how-to/guide, or explanation—or some combination? And for context, what sort(s) of students are we talking here?

Also, do you have any specific concerns you could share about the proposed structure and its effect on your teaching and your students?

[erlend-aasland]

I suggest to remove the Introduction heading (it serves little purpose), and then close this issue.

[CAM-Gerlach]

There are still a couple things that need doing:

• The "How-to" sections should be renamed to avoid "Using", etc. and be more clear they are how tos per Diataxis as you did in the closed Restructure the sqlite3 docs table-of-contents #94635
• Thinking more about it, the "Default Adapters and Converters" section is actually pretty clearly a Reference, and should be moved accordingly

Would you like me to open PRs for these, or do them yourself?

[erlend-aasland]

There are still a couple things that need doing:

• The "How-to" sections should be renamed to avoid "Using", etc. and be more clear they are how tos per Diataxis as you did in the closed Restructure the sqlite3 docs table-of-contents #94635
• Thinking more about it, the "Default Adapters and Converters" section is actually pretty clearly a Reference, and should be moved accordingly

Would you like me to open PRs for these, or do them yourself?

Sure, go ahead :)

[erlend-aasland]

FTR, Daniele's Camera docs repeat "How-to" for subsections:

[CAM-Gerlach]

Will do shortly 👍

I've indeed come around to your reasoning on this 😄

[CAM-Gerlach]

Thanks, opened as #96136

[erlend-aasland]

AFAICS, we can close this. Thanks CAM and Ezio!

[CAM-Gerlach]

Thanks to you for doing most of the work!