aws / aws/aws-lambda-rust-runtime
[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates
- Langage dominant
- Rust
- Étoiles
- 3.6k
- Forks
- 396
- Métriques de merge des PR
- Aucune PR mergée en 30 j
Description
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?
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par lire le README du dépôt et la documentation existante du crate lambda-runtime, puis comparez les approches proposées avec include_str!, un build.rs personnalisé et cargo-readme. Le travail est terminé lorsque du contenu utile du README apparaît sur docs.rs pour lambda-runtime, avec une approche mûrement réfléchie pour lambda-extension et les autres READMEs de crates qui conserve ou remplace correctement la section des badges.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- rust
- Domaine
- documentation
- Type d'issue
- Documentation
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Activité
- À l'abandon
- Clarté
- Plutôt claire
- Accessibilité débutants
- 35/100