aws / aws/aws-lambda-rust-runtime
[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates
- Lingua principale
- Rust
- Stelle
- 3.6k
- Fork
- 396
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
We have a fairly rich README in the repository, but very minimalist `lambda-runtime` docs (same goes for `lambda-extension`, but i think `lambda-runtime` is most important). I know the README already shows in GitHub, and on `crates.io`, but `docs.rs` adds discoverability as well. It gives the impression that the crate is well-maintained (which it is), whereas sparse `docs.rs` docs don't look so great.
Even without a full from-scratch crate docs write, I think it would add a lot of value to make some of the content in the README show up in `docs.rs`.
## How to do it
### Bad options
#### Simple `include_str!`
A simple way to do this would just be to add:
```
#![doc = include_str!("../../README.md")]
```
However the first section with all the badges break. So I don't think this is a good option.
#### `include-utils`
There is a crate, [include-utils](https://docs.rs/include-utils/latest/include_utils/index.html), that does pretty much exactly what we need. It would allow only including a subset of the file, so we would include everything after the first section.
However, it would force a new proc macro-based dependency into our primary dependencies, which I don't love. It also seems maintained but is not widely used.
So, I don't think this is a great option either.
### Good options
#### Custom `build.rs` handling to filter the file
Instead of using the proc macro, we could also just filter the file into what we need via a custom `build.rs`. This is nice too since then we could replace the badges with regular links to the related crates, which would be kind of nice.
The downside here is a bit of added complexity, but I don't mind knocking it out if desired.
#### Move most of docs into crate docs, use `cargo-readme`
The other good option is to flip things around and migrate the source of truth to be the library docs proper. Then the tool [cargo-readme](https://github.com/webern/cargo-readme) lets us generate the markdown `README` from those.
This has the added benefit of making it really easy to add cross-linking to types and functions inside the crate docs, which is nice.
The downside is that now we need to generate README changes via an extra build step. I guess we could add a pre-commit hook to do it so that nobody forgets?
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia leggendo il README del repository e la documentazione esistente del crate lambda-runtime, quindi confronta gli approcci proposti con include_str!, un build.rs personalizzato e cargo-readme. Il lavoro è completato quando su docs.rs per lambda-runtime compare contenuto utile del README e viene definito un percorso ponderato per lambda-extension e per i README degli altri crate, che conservi o sostituisca adeguatamente la sezione dei badge.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- rust
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100