Move examples to rust projects (remove skeptic)

[joshka]

The current approach to writing examples is to write the code directly in the markdown files an then combine and use skeptic for testing.

The downside of this is that it's more difficult to edit the code using the standard rust tooling (rust-analyzer, rustfmt, clippy, etc.)

A better approach (@jamesgraves did this in https://github.com/jamesgraves/rust-cookbook/) is to move all the code into actual projects and then import from files into mdbook (see https://rust-lang.github.io/mdBook/format/mdbook.html#including-files)

Doing this means that in general you can write code, lint it and format it, and then view the code snippet in the book directly. It also means that each snippet can be supported by the relevant cargo manifest necessary just for that snippet rather than a manifest for the entire cookbook, and it makes it possible to run each example directly when you clone the repo.

Implementation

We use this approach successfully in the Ratatui website. This started as an mdbook site and then we moved to using Starlight (a doc site template for Astro). To do this we added the same idea of importing code from files to the stock code block element, and then went a little further to reduce the amount of // ANCHOR comments needed for importing rust functions using tree sitter to parse out just functions of interest. This might be possible to backport into mdbook.

Minor side note (code organization)

I'm not 100% in agreement with the arrangement of where the rust projects end up in the tree in @jamesgraves version. They feel a bit jumbled together which is difficult to navigate. In Ratatui, we had a second root code folder with just the crates / code. This observation is a minor one however, as I think it's much better to have this functionality than to bikeshed on exactly how it's organized. Perhaps there's some hybrid where each crate has a src folder with a docs folder alongside it. That would make it feel less jumbled (I'm not whether it's possible with mdbook to have the file location and url not fully aligned like this)

[jamesgraves]

Here's what motivated me to make the changes to how the cookbook works, in a bit more detail than what was in the CHANGES.md file.

At one point in 2022, the project would not pass cargo test because the skeptic crate was using the wrong version of a dependency for one of the tests. There was more than one version of a dependent crate, and it picked the wrong one to link into a particular example. I wasn't sure how to fix that with the skeptic crate. After learning about cargo workspaces, and how some other projects use code examples, I thought it would be easier to just rip out skeptic, and put all the code into .rs files.

Another benefit was the ability to test and run examples that have OS dependencies, or that interact with the filesystem, such as with the SQLite 3 database section.

And this ties into how I thought the cookbook ought to be used: rather than just looking at the examples and running some of them on the Rust Playground, instead the developer should clone the repository and try any the examples locally. So it is more code-focused rather than documentation-focused, in a sense. That's why I also like having more of the comments in the code, rather than being separate from it, though I understand the other point of view.

While it is nice to have the code and commentary in a single file, to be edited together, I usually just edit both files (the .md and the .rs) in a split window, so not having them in the same file is not a significant downside to me.

---

As far as the file organization in the cookbook, I'm definitely open to ideas about how to organize the directory structure. I haven't put much thought into that since the implementation of workspaces. If the boilerplate needed for cargo test could be consolidated, that would be convenient. I'd want to retain the ability to run cargo test inside a subdirectory, and have it just test the examples in that workspace.

[joshka]

On the organization side I can see how it makes sense after playing with it a bit more. Adding a /doc folder under each crate might be possible with a small mdbook preprocesser that modifies the location of each file. Then you'd have something like:

algorithms
├── randomness
│   ├── doc
│   │   ├── rand-choose.md
│   │   ├── rand-custom.md
│   │   ├── rand-dist.md
│   │   ├── rand-passwd.md
│   │   ├── rand-range.md
│   │   └── rand.md
│   ├── examples
│   │   ├── basic_usage.rs
│   │   ├── gen_range.rs
│   │   ├── generate_password.rs
│   │   ├── normal_distribution.rs
│   │   ├── random_string.rs
│   │   ├── tuple_distribution.rs
│   │   └── uniform_distribution.rs
│   ├── src
│   │   └── lib.rs
│   ├── Cargo.toml
│   └── randomness.md
└── sorting
    ├── doc
    │   ├── sort-float.md
    │   ├── sort-struct.md
    │   └── sort.md
    ├── examples
    │   ├── sort-basic.rs
    │   ├── sort-float.rs
    │   └── sort-struct.rs
    ├── src
    │   └── lib.rs
    ├── Cargo.toml
    └── sorting.md

Something that I would suggest is collapsing the structure to two levels to keep the TOC and folder arrangement a bit simpler (it goes to 3 in some places)

Another thing that might also be worth doing is automating the various lists of recipes with a custom preprocesser. This would keep them in sync pretty easily rather than having a lot of manual docs to do it and reduce the maintenance burden.

On the testing side it could be worth looking at something like trycmd or insta to actually fully test the input / output. Maybe cli output could possibly even be generated and imported directly from each example rather than having to copy paste it in.

[john-cd]

Have a look on how examples are organized in https://github.com/john-cd/rust_howto/tree/main/deps/tests

• Example code have been moved to a separate project ('deps')
• They are written as tests calling a main(), so that (1) the code can be copied-pasted and (ii) fully tested in CI
• Examples / tests are grouped via modules, meaning cargo nextest / test only have to compile a few executables and test exec is fast

[joshka]

Sounds like there's 3 versions of the same thing now. Perhaps it could be worth doing a audit of how these crossover and consolidating them rather than duplicating effort.

[AndyGauge]

While I like how skeptic made the testing unobtrusive, it left a real gap with maintenance. Patching skeptic is hard, and the explicit testing strategy is much easier to reason, despite having to maintain test files. Unless @djc objects, I am in favor of manually testing all the recipes, despite the expensive overhaul. I'm also in favor of only fixing recipes that haven't already been fixed by others, coordinating the remaining effort, and delivering a collaborative product.

I believe @shepmaster would need to weigh in if the Cargo.toml leverages workspaces if the Playground could read it. I thought the idea was a batteries included Cargo.toml file you could start a project with and just load any of the recipes as the main.rs file

[djc]

I have no objections. I don't think skeptic is really the right solution and it seems to have a lot of complexity that isn't really necessary.

[shepmaster]

if the Cargo.toml leverages workspaces if the Playground could read it

Yeah it will be fine.

[AndyGauge]

Let's go!

[AndyGauge]

Proposed leveraging modules for recipes to make the cookbook more of a banquet than a single course treat. I've started working on web. The important part is web is crate you can download and just update the types for your own api and pick and choose the modules you need.

thoughts?

[joshka]

I'd suggest going one step further and putting all the code in the rust file (including the main.rs), not just the lib call.