{"id":13741794,"url":"https://github.com/sourcegraph/prototools","last_synced_at":"2025-05-08T22:32:25.789Z","repository":{"id":31227428,"uuid":"34788606","full_name":"sourcegraph/prototools","owner":"sourcegraph","description":"documentation generator \u0026 other tools for protobuf/gRPC","archived":false,"fork":false,"pushed_at":"2021-03-31T12:40:15.000Z","size":88,"stargazers_count":171,"open_issues_count":5,"forks_count":27,"subscribers_count":85,"default_branch":"master","last_synced_at":"2025-05-04T04:39:24.024Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcegraph.png","metadata":{"files":{"readme":"README.doc.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-29T10:52:54.000Z","updated_at":"2025-04-22T17:44:55.000Z","dependencies_parsed_at":"2022-08-30T23:22:07.779Z","dependency_job_id":null,"html_url":"https://github.com/sourcegraph/prototools","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcegraph%2Fprototools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcegraph%2Fprototools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcegraph%2Fprototools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcegraph%2Fprototools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcegraph","download_url":"https://codeload.github.com/sourcegraph/prototools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253158309,"owners_count":21863273,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T04:01:02.709Z","updated_at":"2025-05-08T22:32:25.402Z","avatar_url":"https://github.com/sourcegraph.png","language":"Go","readme":"# protoc-gen-doc\n\n`cmd/protoc-gen-doc` contains a protoc compiler plugin for documentation generation of `.proto` files. It operates on standard Go `html/template` files (see the `templates` directory) and as such can produce HTML documentation.\n\n## Installation\n\nFirst install Go and Protobuf itself, then install the plugin using go get:\n\n```\ngo get -u sourcegraph.com/sourcegraph/prototools/cmd/protoc-gen-doc\n```\n\n## Usage\n\nSimply invoke `protoc` with the `--doc_out` command-line parameter:\n\n```\nprotoc --doc_out=\"\u003cOUT_DIR\u003e\" input.proto\nprotoc --doc_out=\"\u003cOPTIONS\u003e:\u003cOUT_DIR\u003e\" input.proto\n```\n\nWhere `\u003cOPTIONS\u003e` is a comma-seperated list of `key=value,key2=value2` options (which are listed in detail below). For example:\n\n```\nprotoc --doc_out=\"doc/\" file.proto\n```\n\nWould produce documentation for `file.proto` inside the `doc/` directory using the template `templates/tmpl.html` HTML template file.\n\n## Options\n\n| Option         | Default                     | Description                                                        |\n|----------------|-----------------------------|--------------------------------------------------------------------|\n| `template`     | `templates/tmpl.html`       | Input `.html` `html/template` template file to use for generation. |\n| `root`         | (current working directory) | Root directory path to prefix all generated URLs with.             |\n| `filemap`      | none                        | A XML filemap, which specifies how output files are generated.     |\n| `dump-filemap` | none                        | Dump the executed filemap template to the given filepath.          |\n| `apihost`      | none                        | (grpc-gateway) API host base URL (e.g. `api.mysite.com`, no colons in value)   |\n| `conf`         | none                        | Comma-separated text configuration file with these very options.   |\n\nThe `template` and `filemap` options are exclusive (only one may be used at a time).\n\n## Templates\n\nTemplate files are standard Go `html/template` files, and as such their documentation can be found [in that package](https://golang.org/pkg/html/template).\n\n## File Maps\n\nIn many cases producing a single output `.html` file for a single input `.proto` file is not desired, often producing very verbose or long web pages. Because protoc-gen-doc doesn't really know how you want your documentation laid out on the file-system (and does not want to restrict you), we offer templated XML file maps.\n\nSay for example that we wanted to produce documentation for three gRPC services, all of which are declared inside of a `organization/services.proto` file:\n\n- \"Producer\" -\u003e `out_dir/organization/service-producer.html`\n- \"Consumer\" -\u003e `out_dir/organization/service-consumer.html`\n- \"Trader\"   -\u003e `out_dir/organization/service-trader.html`\n\nAnd also an `out_dir/index.html` file which will link to the three services.\n\nIn order to produce the above three (plus index) files for the single `services.proto` file, we will use an XML filemap that follows the syntax of:\n\n```\n\u003cFileMap\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003epath/to/template.html\u003c/Template\u003e\n        \u003cTarget\u003epath/to/target.proto\u003c/Target\u003e \u003c!-- optional --\u003e\n        \u003cOutput\u003epath/to/output.html\u003c/Output\u003e\n        \u003cIncludes\u003e\n            \u003cInclude\u003ea.tmpl\u003c/Include\u003e\n            \u003cInclude\u003eb.tmpl\u003c/Include\u003e\n        \u003c/Includes\u003e\n        \u003cData\u003e\n            \u003cItem\u003e\u003cKey\u003emyKey1\u003c/Key\u003e\u003cValue\u003emyValue1\u003c/Value\u003e\u003c/Item\u003e\n            \u003cItem\u003e\u003cKey\u003emyKey2\u003c/Key\u003e\u003cValue\u003emyValue2\u003c/Value\u003e\u003c/Item\u003e\n        \u003c/Data\u003e\n    \u003c/Generate\u003e\n    \u003cGenerate\u003e\n        ...\n    \u003c/Generate\u003e\n\u003c/FileMap\u003e\n```\n\nWhere `\u003cTemplate\u003e` and `\u003cInclude\u003e` paths are relative to the XML filemap directory, `\u003cOutput\u003e` paths are relative to the output directory, and `\u003cTarget\u003e` paths are relative to `--proto_path` directories.\n\nThus we would write:\n\n```\n\u003cFileMap\u003e\n    \u003c!-- Index Page (notice the lack of target tag) --\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003eindex.html\u003c/Template\u003e\n        \u003cOutput\u003eindex.html\u003c/Output\u003e\n    \u003c/Generate\u003e\n\n    \u003c!-- Service Pages --\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003eservice.html\u003c/Template\u003e\n        \u003cTarget\u003eorganization/services.proto\u003c/Target\u003e\n        \u003cOutput\u003eorganization/service-producer.html\u003c/Output\u003e\n        \u003cData\u003e\n            \u003cItem\u003e\u003cKey\u003eService\u003c/Key\u003e\u003cValue\u003eProducer\u003c/Value\u003e\u003c/Item\u003e\n        \u003c/Data\u003e\n    \u003c/Generate\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003eservice.html\u003c/Template\u003e\n        \u003cTarget\u003eorganization/services.proto\u003c/Target\u003e\n        \u003cOutput\u003eorganization/service-consumer.html\u003c/Output\u003e\n        \u003cData\u003e\n            \u003cItem\u003e\u003cKey\u003eService\u003c/Key\u003e\u003cValue\u003eConsumer\u003c/Value\u003e\u003c/Item\u003e\n        \u003c/Data\u003e\n    \u003c/Generate\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003eservice.html\u003c/Template\u003e\n        \u003cTarget\u003eorganization/services.proto\u003c/Target\u003e\n        \u003cOutput\u003eorganization/service-trader.html\u003c/Output\u003e\n        \u003cData\u003e\n            \u003cItem\u003e\u003cKey\u003eService\u003c/Key\u003e\u003cValue\u003eTrader\u003c/Value\u003e\u003c/Item\u003e\n        \u003c/Data\u003e\n    \u003c/Generate\u003e\n\u003c/FileMap\u003e\n```\n\nAs you can see, for just three types it quickly becomes very cumbersome. For this reason filemaps _are themselves templates_ (this is also the rational for choosing XML over e.g. JSON), so we can write the above instead using `html/template` syntax:\n\n```\n\u003cFileMap\u003e\n    \u003c!-- Index Page (notice the lack of target tag) --\u003e\n    \u003cGenerate\u003e\n        \u003cTemplate\u003eindex.html\u003c/Template\u003e\n        \u003cOutput\u003eindex.html\u003c/Output\u003e\n    \u003c/Generate\u003e\n\n{{$serviceTemplate := \"service.html\"}}\n{{range $f := .ProtoFile}}\n    {{range $s := .Service}}\n        \u003cGenerate\u003e\n            \u003cTemplate\u003e{{$serviceTemplate}}\u003c/Template\u003e\n            \u003cTarget\u003e{{$f.Name}}\u003c/Target\u003e\n            \u003cOutput\u003e{{dir $f.Name}}/{{$s.Name}}{{ext $serviceTemplate}}\u003c/Output\u003e\n            \u003cData\u003e\n                \u003cItem\u003e\u003cKey\u003eService\u003c/Key\u003e\u003cValue\u003e{{$s.Name}}\u003c/Value\u003e\u003c/Item\u003e\n            \u003c/Data\u003e\n        \u003c/Generate\u003e\n    {{end}}\n{{end}}\n\u003c/FileMap\u003e\n```\n\nWhich is to say: for every service type (`range $s := .Service`) in every protobuf input file (`range $f := .ProtoFile` and `\u003cTarget\u003e{{$f.Name}}\u003c/Target\u003e`) generate a output file using the Go `html/template` (`{{$serviceTemplate}}`) placing output in the directory the protobuf file is in (`{{$f.Name}}`, `organization` in our example), with the service types name (`{{$s.Name}}`, or `Producer` `Consumer` `Trader` above) with the extension of the `$serviceTemplate` file (`.html`), and when each `\u003cTemplate\u003e` is executed pass along a map with the given keys/values (the service template can then selectively render _just that service type_).\n\nFor debugging purposes, you can use the `dump-filemap` option which will execute the template and dump the resulting XML out to a file.\n\n## Issues\n\nIf you run into trouble or have questions, please [open an issue](https://github.com/sourcegraph/prototools/issues/new).\n","funding_links":[],"categories":["Protocol Buffers"],"sub_categories":["Tools"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcegraph%2Fprototools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcegraph%2Fprototools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcegraph%2Fprototools/lists"}