Guide Structure and Story

[somethingelseentirely]

Working through the guide to learn PyO3 has not been as smooth as working through some of the other rust/library books.

After some discussion and reflection I feel that this is due to the following:

• It is has a lot of what, but does not motivate the why well.
• There is a lot of redundant information but very little of it is directly actionable, e.g. examples show general mechanisms but not common usage.
• The separation of the guide into Using Rust from Python and Calling Python from Rust sounds like a good idea at first, but is a bad abstraction in practice. Both extending and embedding Python shares a lot of the API's surface, and since PyO3 is a Rust library the user will take the perspective looking from Rust at Python most of the time (from a Python perspective things behave just like native objects).
• By trying to be both a reference and a guide it serves neither purpose well.

I would like to rework the guide with a focus on a coherent story and explanations that motivate each mechanism/concept in the context of previous content.

An outline for this guide could look like this (incomplete and just to illustrate the story):

# Getting Started
## Installation
## Embedding the Python Interpreter in Rust
## Writing Python Modules with Rust
# Bridging the Gap Between Python and Rust
## Python Objects in Rust
### Python Types
#### Python vs. Rust Type System
### Smart Pointers
#### Python vs. Rust Memory Model
### Python Types in Depth
#### Casting Between Python Types
#### Concrete Python Type APIs
## Modules
## Functions
## Classes
## Python Memory Model Continued: Integrating with the GC
# In Depth Under the Hood
## Functions and #[pyfunction]
## Classes and #[pyclass]

It might be a good idea to also consider that users might have a Rust or Python background, and provide additional explanations in flavoured text boxes, to keep the overall explanations concise but still provide the in-depth insight that each group might need.

As part of learning PyO3 I'm currently rewriting the guide just like I would take lecture notes, maybe it provides a good feeling for the style that I'm looking for:
https://github.com/somethingelseentirely/pyo3/blob/patch-1/guide/src/types.md