[DOC] Generate gRPC API reference from the .proto files

Abierto
  • ¿Algo no está bien?
#2,121 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
50/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
grpc
Área
api, documentation

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

doc

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.rst lists 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 from cpp/src/grpc/codegen/field_registry.yaml and committed under cpp/src/grpc/codegen/generated/.
  • The element layout and dtype of each array is documented only in comments on ArrayFieldId and the nested ArrayId enums. 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 in cpp/src/grpc/GRPC_INTERFACE.md, which the published docs don't include or link to.
  • The protos are not in the libcuopt-client wheel 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.proto and cuopt_routing_solution.proto.
  • Link them from cuopt-grpc/api.rst, and add :download: links to the .proto files.
  • Bring the content of GRPC_INTERFACE.md into the docs, or link to it.
  • Fix the file-name list in api.rst so it includes cuopt_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.
Lenguaje dominante
Cuda
Estrellas
1.1k
Forks
249
Merge medio
1 d 11 h
PR fusionados (30 d)
123

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de NVIDIA/cuopt

Todos los issues de NVIDIA/cuopt

Issues similares

Más issues de Backend & API Design

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.