[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates
维护者通常 8 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 停滞
- 技术栈
- rust
调研方向
首先阅读仓库README和现有的lambda-runtime crate文档，然后比较所提议的include_str!、自定义build.rs和cargo-readme方案。当lambda-runtime的docs.rs中出现有用的README内容，并且为lambda-extension及其他crate的README确定了经过审慎考虑的路径，适当地保留或替换徽章部分时，工作就完成了。
由索引模型根据 Issue 内容生成。
描述
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?
- 主要语言
- Rust
- 星标
- 3.6k
- 派生
- 397
- 平均合并
- 5 天 14 小时
- 30 天内合并 PR
- 2
环境准备
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
aws/aws-lambda-rust-runtime 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 62/100
aws/aws-lambda-rust-runtime#1099 · 1 个 reaction ·
维护者通常 8 天内回复
-
难度 3/5 1-2 天 新手友好度 74/100
aws/aws-lambda-rust-runtime#1165 ·
维护者通常 8 天内回复
-
难度 3/5 1-2 天 新手友好度 68/100
aws/aws-lambda-rust-runtime#1161 ·
维护者通常 8 天内回复
-
Add Lambda-Runtime-Invocation-Id header support for cross-wiring protection可能重新可做 @darklight3it 于 62 天前认领，目前没有进行中的 PR。 未关闭
aws/aws-lambda-rust-runtime#1155 · 1 个 reaction · 已指派 1 人 ·
维护者通常 8 天内回复
-
难度 3/5 1-2 天 新手友好度 48/100
aws/aws-lambda-rust-runtime#1131 · 1 条评论 ·
维护者通常 8 天内回复
查看 aws/aws-lambda-rust-runtime 的全部 Issue
相似的 Issue
-
`categorize_command` has no `uv` arm, so every `rtk uv …` row counts as `other` in the ecosystem mix未关闭area:api bug good first issue priority:low
难度 1/5 1 小时以内 新手友好度 92/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 92/100
维护者通常 1 天内回复
-
area/cli kind/bug
难度 2/5 1-3 小时 新手友好度 90/100
维护者通常 1 天内回复
-
enhancement
难度 2/5 1-3 小时 新手友好度 72/100
-
good first issue open-endedness: low type: new feature
难度 2/5 1-3 小时 新手友好度 72/100