aws / aws/aws-lambda-rust-runtime

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

Đang mở
#990 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Rust
Star
3.6k
Fork
396
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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?

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Bắt đầu bằng cách đọc README của repository và tài liệu hiện có của crate lambda-runtime, sau đó so sánh các phương án được đề xuất sử dụng include_str!, build.rs tùy chỉnh và cargo-readme. Công việc hoàn tất khi nội dung README hữu ích xuất hiện trên docs.rs cho lambda-runtime, cùng với một hướng đi được cân nhắc kỹ cho lambda-extension và README của các crate khác, trong đó phần badge được giữ lại hoặc thay thế một cách phù hợp.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
rust
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
35/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.