History

Will Jones c59300f551 Generate reference documentation from Protobufs (#17120 ) Protocol buffer (Protobuf) definitions are the source of truth for many of the types and interfaces used across Pulumi products. Documentation written in Protobuf files is already used to generate commented code e.g. when producing gRPC stubs and clients. This commit extends this to generate reference developer documentation from our Protobuf files using the `protoc-gen-doc` plugin for `protoc`, which exports Protobuf documentation as Markdown. This is then incorporated into the build process for our developer documentation so that we can refer to Protobuf types and gRPC services and messages across our documentation. In order to provide a degree of portability, and also not to require developers (or the Read the Docs build process) to download and manage the `protoc` / `protoc-gen-doc` toolchains required, this commit introduces a `make.py` Python script that encapsulates the more complicated steps of the build without having to resort to reams of shell scripts. This script is still invoked from the `Makefile` and Make is still responsible for dependency tracking (e.g. recognising that generating Protobuf documentation must happen before running the Sphinx build, and so on).	2024-08-30 17:04:16 +00:00
..
README.md	Generate reference documentation from Protobufs (#17120 )	2024-08-30 17:04:16 +00:00
proto.md.tmpl	Generate reference documentation from Protobufs (#17120 )	2024-08-30 17:04:16 +00:00

Generate reference documentation from Protobufs (#17120 )

Protocol buffer (Protobuf) definitions are the source of truth for many
of the types and interfaces used across Pulumi products. Documentation
written in Protobuf files is already used to generate commented code
e.g. when producing gRPC stubs and clients. This commit extends this to
generate reference developer documentation from our Protobuf files using
the `protoc-gen-doc` plugin for `protoc`, which exports Protobuf
documentation as Markdown. This is then incorporated into the build
process for our developer documentation so that we can refer to Protobuf
types and gRPC services and messages across our documentation.

In order to provide a degree of portability, and also not to require
developers (or the Read the Docs build process) to download and manage
the `protoc` / `protoc-gen-doc` toolchains required, this commit
introduces a `make.py` Python script that encapsulates the more
complicated steps of the build without having to resort to reams of
shell scripts. This script is still invoked from the `Makefile` and Make
is still responsible for dependency tracking (e.g. recognising that
generating Protobuf documentation must happen before running the Sphinx
build, and so on).

2024-08-30 17:04:16 +00:00

README.md

Generate reference documentation from Protobufs (#17120 )

2024-08-30 17:04:16 +00:00

proto.md.tmpl

Generate reference documentation from Protobufs (#17120 )

2024-08-30 17:04:16 +00:00

README.md

References

This section of the documentation is intended to serve as an index for various pieces of machine-generated documentation (e.g. docstrings from Protobuf files, TypeDocs from the NodeJS/TypeScript SDK, and so on).

:::{toctree} :maxdepth: 2 :titlesonly:

/proto/README :::