[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates
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
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- 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.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của aws/aws-lambda-rust-runtime
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 62/100
aws/aws-lambda-rust-runtime#1099 · 1 reaction ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 74/100
aws/aws-lambda-rust-runtime#1165 ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 68/100
aws/aws-lambda-rust-runtime#1161 ·
-
aws/aws-lambda-rust-runtime#1155 · 1 reaction · 1 người được giao ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 48/100
aws/aws-lambda-rust-runtime#1131 · 1 bình luận ·
Tất cả issue của aws/aws-lambda-rust-runtime
Issue tương tự
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
TheLarkInn/aipm#2413 ·
-
documentation
Độ khó 1/5 Dưới một giờ Mức phù hợp với người mới 90/100
alexgorbatchev/simple-ptt#15 ·
-
tooling
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
-
todo:ticket
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 70/100
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 75/100
taikoxyz/taiko-mono#22168 · 1 bình luận ·