aws / aws/aws-lambda-rust-runtime

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

オープン
#990 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る
主要言語
Rust
スター
3.6k
フォーク
396
PR マージ指標
30日以内にマージされた PR はありません

説明

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?

コントリビューションガイド

コントリビューションガイドを開く

調査の方向性

まずリポジトリのREADMEと既存のlambda-runtime crateのドキュメントを読み、次に提案されているinclude_str!、カスタムbuild.rs、cargo-readmeのアプローチを比較します。lambda-runtimeのdocs.rsに有用なREADMEの内容が表示され、lambda-extensionや他のcrateのREADMEについて、バッジセクションを適切に維持するか置き換えるかを含む、検討された方針が定まった時点で作業は完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
rust
領域
documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
35/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。