{"id":13511609,"url":"https://github.com/pseudomuto/protoc-gen-doc","last_synced_at":"2025-05-12T15:38:22.768Z","repository":{"id":19342662,"uuid":"22581723","full_name":"pseudomuto/protoc-gen-doc","owner":"pseudomuto","description":"Documentation generator plugin for Google Protocol Buffers","archived":false,"fork":false,"pushed_at":"2025-02-11T14:03:18.000Z","size":942,"stargazers_count":2725,"open_issues_count":123,"forks_count":479,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-23T17:50:32.118Z","etag":null,"topics":["documentation-tool","go","golang","hacktoberfest","hacktoberfest2021","protobuf","protoc"],"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/pseudomuto.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-03T19:14:42.000Z","updated_at":"2025-04-21T22:38:55.000Z","dependencies_parsed_at":"2024-04-16T20:58:04.570Z","dependency_job_id":"e683185a-606e-47da-9332-616a1982af9b","html_url":"https://github.com/pseudomuto/protoc-gen-doc","commit_stats":{"total_commits":436,"total_committers":34,"mean_commits":"12.823529411764707","dds":"0.45642201834862384","last_synced_commit":"00cf69cfa432cb7ff4218bd2106290716423400e"},"previous_names":["estan/protoc-gen-doc"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fprotoc-gen-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fprotoc-gen-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fprotoc-gen-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pseudomuto%2Fprotoc-gen-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pseudomuto","download_url":"https://codeload.github.com/pseudomuto/protoc-gen-doc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253766804,"owners_count":21960996,"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":["documentation-tool","go","golang","hacktoberfest","hacktoberfest2021","protobuf","protoc"],"created_at":"2024-08-01T03:01:00.151Z","updated_at":"2025-05-12T15:38:22.654Z","avatar_url":"https://github.com/pseudomuto.png","language":"Go","funding_links":[],"categories":["Go","开源类库","Go (134)","Protocol Buffers","Documentation Types","Repositories"],"sub_categories":["序列化","Tools","API Documentation"],"readme":"# protoc-gen-doc\n\n[![CI Status][ci-svg]][ci-url]\n[![codecov][codecov-svg]][codecov-url]\n[![GoDoc][godoc-svg]][godoc-url]\n[![Go Report Card][goreport-svg]][goreport-url]\n\nThis is a documentation generator plugin for the Google Protocol Buffers compiler (`protoc`). The plugin can generate\nHTML, JSON, DocBook, and Markdown documentation from comments in your `.proto` files.\n\nIt supports proto2 and proto3, and can handle having both in the same context (see [examples](examples/) for proof).\n\n## Installation\n\nThere is a Docker image available (`docker pull pseudomuto/protoc-gen-doc`) that has everything you need to generate\ndocumentation from your protos.\n\nIf you'd like to install this locally, you can `go get` it.\n\n`go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest`\n\nAlternatively, you can download a pre-built release for your platform from the [releases][] page.\n\nFinally, this plugin is also available on Maven Central. For details about how to use it, check out the [gradle\nexample](examples/gradle).\n\n## Invoking the Plugin\n\nThe plugin is invoked by passing the `--doc_out`, and `--doc_opt` options to the `protoc` compiler. The option has the\nfollowing format:\n\n    --doc_opt=\u003cFORMAT\u003e|\u003cTEMPLATE_FILENAME\u003e,\u003cOUT_FILENAME\u003e[,default|source_relative]\n\nThe format may be one of the built-in ones ( `docbook`, `html`, `markdown` or `json`)\nor the name of a file containing a custom [Go template][gotemplate].\n\nIf the `source_relative` flag is specified, the output file is written in the same relative directory as the input file.\n\n### Using the Docker Image (Recommended)\n\nThe docker image has two volumes: `/out` and `/protos` which are the directory to write the documentation to and the\ndirectory containing your proto files.\n\nYou could generate HTML docs for the examples by running the following:\n\n```\ndocker run --rm \\\n  -v $(pwd)/examples/doc:/out \\\n  -v $(pwd)/examples/proto:/protos \\\n  pseudomuto/protoc-gen-doc\n```\n\nBy default HTML documentation is generated in `/out/index.html` for all `.proto` files in the `/protos` volume. This can\nbe changed by passing the `--doc_opt` parameter to the container.\n\nFor example, to generate Markdown for all the examples:\n\n```\ndocker run --rm \\\n  -v $(pwd)/examples/doc:/out \\\n  -v $(pwd)/examples/proto:/protos \\\n  pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md\n```\n\nYou can also generate documentation for a single file. This can be done by passing the file(s) to the command:\n\n```\ndocker run --rm \\\n  -v $(pwd)/examples/doc:/out \\\n  -v $(pwd)/examples/proto:/protos \\\n  pseudomuto/protoc-gen-doc --doc_opt=markdown,docs.md Booking.proto [OPTIONALLY LIST MORE FILES]\n```\n\nYou can also exclude proto files that match specific path expressions. This is done by passing a second option delimited\nby `:`. For example, you can pass any number of comma separated patterns as the second option:\n\n```\ndocker run --rm \\\n  -v $(pwd)/examples/doc:/out \\\n  -v $(pwd)/examples/proto:/protos \\\n  pseudomuto/protoc-gen-doc --doc_opt=:google/*,somepath/*\n```\n\n_**Remember**_: Paths should be from within the container, not the host!\n\n\u003e NOTE: Due to the way wildcard expansion works with docker you cannot use a wildcard path (e.g. `protos/*.proto`) in\nthe file list. To get around this, if no files are passed, the container will generate docs for `protos/*.proto`, which\ncan be changed by mounting different volumes.\n\n### Simple Usage\n\nFor example, to generate HTML documentation for all `.proto` files in the `proto` directory into `doc/index.html`, type:\n\n    protoc --doc_out=./doc --doc_opt=html,index.html proto/*.proto\n\nThe plugin executable must be in `PATH` for this to work. \n\n### Using a precompiled binary\n\nAlternatively, you can specify a pre-built/not in `PATH` binary using the `--plugin` option.\n\n    protoc \\\n      --plugin=protoc-gen-doc=./protoc-gen-doc \\\n      --doc_out=./doc \\\n      --doc_opt=html,index.html \\\n      proto/*.proto\n\n### With a Custom Template\n\nIf you'd like to use your own template, simply use the path to the template file rather than the type.\n\n    protoc --doc_out=./doc --doc_opt=/path/to/template.tmpl,index.txt proto/*.proto\n\nFor information about the available template arguments and functions, see [Custom Templates][custom]. If you just want\nto customize the look of the HTML output, put your CSS in `stylesheet.css` next to the output file and it will be picked\nup.\n\n## Writing Documentation\n\nMessages, Fields, Services (and their methods), Enums (and their values), Extensions, and Files can be documented.\nGenerally speaking, comments come in 2 forms: leading and trailing.\n\n**Leading comments**\n\nLeading comments can be used everywhere.\n\n```protobuf\n/**\n * This is a leading comment for a message\n */\nmessage SomeMessage {\n  // this is another leading comment\n  string value = 1;\n}\n```\n\n\u003e NOTE: File level comments should be leading comments on the syntax directive.\n\n**Trailing comments**\n\nFields, Service Methods, Enum Values and Extensions support trailing comments.\n\n```protobuf\nenum MyEnum {\n  DEFAULT = 0; // the default value\n  OTHER   = 1; // the other value\n}\n```\n\n**Excluding comments**\n\nIf you want to have some comment in your proto files, but don't want them to be part of the docs, you can simply prefix\nthe comment with `@exclude`. \n\nExample: include only the comment for the `id` field\n\n```protobuf\n/**\n * @exclude\n * This comment won't be rendered\n */\nmessage ExcludedMessage {\n  string id   = 1; // the id of this message.\n  string name = 2; // @exclude the name of this message\n\n  /* @exclude the value of this message. */\n  int32 value = 3;\n}\n```\n\nCheck out the [example protos](examples/proto) to see all the options.\n\n## Output Example\n\nWith the input `.proto` files\n\n* [Booking.proto](examples/proto/Booking.proto)\n* [Customer.proto](examples/proto/Customer.proto)\n* [Vehicle.proto](examples/proto/Vehicle.proto)\n\nthe plugin gives the output\n\n* [Markdown](examples/doc/example.md)\n* [HTML][html_preview]\n* [DocBook](examples/doc/example.docbook)\n* [JSON](examples/doc/example.json)\n\nCheck out the `examples` task in the [Makefile](Makefile) to see how these were generated.\n\n[gotemplate]:\n    https://golang.org/pkg/text/template/\n    \"Template - The Go Programming Language\"\n[custom]:\n    https://github.com/pseudomuto/protoc-gen-doc/wiki/Custom-Templates\n    \"Custom templates instructions\"\n[html_preview]:\n    https://rawgit.com/pseudomuto/protoc-gen-doc/master/examples/doc/example.html\n    \"HTML Example Output\"\n[codecov-svg]: https://codecov.io/gh/pseudomuto/protoc-gen-doc/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/pseudomuto/protoc-gen-doc\n[godoc-svg]: https://godoc.org/github.com/pseudomuto/protoc-gen-doc?status.svg\n[godoc-url]: https://godoc.org/github.com/pseudomuto/protoc-gen-doc\n[goreport-svg]: https://goreportcard.com/badge/github.com/pseudomuto/protoc-gen-doc\n[goreport-url]: https://goreportcard.com/report/github.com/pseudomuto/protoc-gen-doc\n[ci-svg]: https://github.com/pseudomuto/protoc-gen-doc/actions/workflows/ci.yaml/badge.svg?branch=master\n[ci-url]: https://github.com/pseudomuto/protoc-gen-doc/actions/workflows/ci.yaml\n[releases]: https://github.com/pseudomuto/protoc-gen-doc/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpseudomuto%2Fprotoc-gen-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpseudomuto%2Fprotoc-gen-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpseudomuto%2Fprotoc-gen-doc/lists"}