Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

[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

Chưa có ai nhận issue này.

Đánh giá

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

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.

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, 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 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?

Ngôn ngữ chính
Rust
Star
3.6k
Fork
397
Merge trung bình
55 phút
Pull request đã merge (30 ngày)
1

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

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

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của aws/aws-lambda-rust-runtime

Tất cả issue của aws/aws-lambda-rust-runtime

Issue tương tự

Thêm issue về Rust

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.