[DOC] Generate gRPC API reference from the .proto files
维护者通常 1 天内回复
还没有人认领这个 Issue。
评估
- 难度
- 3/5
- 预计耗时
- 1-2 天
- 新手友好度
- 50/100
- Issue 类型
- 文档
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- grpc
- 领域
- api, documentation
调研方向
Start with docs/cuopt/source/cuopt-grpc/api.rst, which lists the proto paths and is missing cuopt_remote_data.proto, and with cpp/src/grpc/GRPC_INTERFACE.md for the wire-format content. Check whether the comments on ArrayFieldId and ArrayId in cpp/src/grpc/codegen/generated/cuopt_remote_data.proto are complete enough to generate from, and pick a generator such as protoc-gen-doc for the docs build. Done means reference pages exist for the five .proto files, api.rst links them with :download: links to the protos, and GRPC_INTERFACE.md is included or linked.
由索引模型根据 Issue 内容生成。
描述
Problem
Anyone writing their own client for cuopt_grpc_server has to work from the .proto files, but the published docs don't carry them:
docs/cuopt/source/cuopt-grpc/api.rstlists four repo paths as plain text. There are no links, downloads or includes.cuopt_remote_data.proto, which holds the actual LP/MIP/QP problem fields, is not listed. It is generated fromcpp/src/grpc/codegen/field_registry.yamland committed undercpp/src/grpc/codegen/generated/.- The element layout and dtype of each array is documented only in comments on
ArrayFieldIdand the nestedArrayIdenums. The docs don't show those comments. - The chunked-transfer wire format (raw native-endian bytes,
container_field_num/container_index, NUL-joined string blobs, message-size limits) is incpp/src/grpc/GRPC_INTERFACE.md, which the published docs don't include or link to. - The protos are not in the
libcuopt-clientwheel I checked, so users must find them in git at the matching release.
Proposal
Generate reference pages from the protos during the docs build, for example with protoc-gen-doc. The field comments then flow into the docs and can't drift from the code.
- Generate pages for
cuopt_remote_service.proto,cuopt_remote.proto,cuopt_remote_data.proto,cuopt_routing.protoandcuopt_routing_solution.proto. - Link them from
cuopt-grpc/api.rst, and add:download:links to the.protofiles. - Bring the content of
GRPC_INTERFACE.mdinto the docs, or link to it. - Fix the file-name list in
api.rstso it includescuopt_remote_data.proto.
Notes
- Check that the proto comments are complete enough to serve as the reference. The generated pages are only as good as those comments.
- Shipping the protos with a release package and adding server reflection are separate options and are not part of this issue.
- 主要语言
- Cuda
- 星标
- 1.1k
- 派生
- 249
- 平均合并
- 1 天 15 小时
- 30 天内合并 PR
- 126
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue，再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库，在一个分支上完成修改。
- 提交 Pull Request，并在描述里引用这个 Issue 编号。
NVIDIA/cuopt 的其他 Issue
-
难度 2/5 1-3 小时 新手友好度 72/100
维护者通常 1 天内回复
-
难度 1/5 1 小时以内 新手友好度 82/100
维护者通常 1 天内回复
-
难度 4/5 3-5 天 新手友好度 32/100
维护者通常 1 天内回复
-
难度 4/5 3-5 天 新手友好度 22/100
NVIDIA/cuopt#2255 · 1 个 reaction ·
维护者通常 1 天内回复
-
难度 3/5 半天 新手友好度 50/100
维护者通常 1 天内回复
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 80/100
OrchardCMS/OrchardCore#20192 ·
维护者通常 1 天内回复
-
0. Needs triage 35-feedback bug
难度 1/5 1 小时以内 新手友好度 62/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 72/100
getgrav/grav-plugin-api#74 ·
-
enhancement freigegeben Haushalts-Admin
难度 2/5 1-3 小时 新手友好度 62/100
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 75/100
btclib-org/btclib-wallet#667 ·
维护者通常 1 天内回复