aws / aws/aws-lambda-rust-runtime

[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates

Ouverte
#990 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
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

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.