{"id":37158974,"url":"https://github.com/flyteorg/protoc-gen-doc","last_synced_at":"2026-01-14T18:59:48.075Z","repository":{"id":50974717,"uuid":"370908447","full_name":"flyteorg/protoc-gen-doc","owner":"flyteorg","description":"Documentation generator plugin for Google Protocol Buffers","archived":false,"fork":true,"pushed_at":"2021-05-27T06:29:24.000Z","size":849,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-02-28T14:06:51.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"pseudomuto/protoc-gen-doc","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyteorg.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}},"created_at":"2021-05-26T04:45:01.000Z","updated_at":"2024-02-28T14:06:51.918Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flyteorg/protoc-gen-doc","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/flyteorg/protoc-gen-doc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyteorg%2Fprotoc-gen-doc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyteorg%2Fprotoc-gen-doc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyteorg%2Fprotoc-gen-doc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyteorg%2Fprotoc-gen-doc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyteorg","download_url":"https://codeload.github.com/flyteorg/protoc-gen-doc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyteorg%2Fprotoc-gen-doc/sbom","scorecard":{"id":405238,"data":{"date":"2025-08-11","repo":{"name":"github.com/flyteorg/protoc-gen-doc","commit":"88753f100bc316a7bffd393cb658d49013582fb1"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.6,"checks":[{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":0,"reason":"Found 0/29 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: containerImage not pinned by hash: Dockerfile:1: pin your Docker image by updating debian:jessie-slim to debian:jessie-slim@sha256:b9b0e7354098cbd534861d7532c082fb81cdb4d893303ba1f322f52c9e583cd2","Info:   0 out of   1 containerImage dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.md:0","Info: FSF or OSI recognized license: MIT License: LICENSE.md:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":0,"reason":"15 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2021-0053 / GHSA-c3h9-896r-86jm","Warn: Project is vulnerable to: GO-2022-0209 / GHSA-r5c5-pr8j-pfp7","Warn: Project is vulnerable to: GO-2023-1992 / GHSA-x3jr-pf6g-c48f","Warn: Project is vulnerable to: GO-2022-0229 / GHSA-cjjc-xp8v-855w","Warn: Project is vulnerable to: GO-2020-0012 / GHSA-ffhg-7mh4-33c4","Warn: Project is vulnerable to: GO-2021-0227 / GHSA-3vm4-22fp-5rfm","Warn: Project is vulnerable to: GO-2022-0968 / GHSA-gwc9-m7rh-j2ww","Warn: Project is vulnerable to: GO-2021-0356 / GHSA-8c26-wmh5-6g9v","Warn: Project is vulnerable to: GO-2024-2961","Warn: Project is vulnerable to: GO-2023-2402 / GHSA-45x7-px36-x8w8","Warn: Project is vulnerable to: GO-2024-3321 / GHSA-v778-237x-gjrc","Warn: Project is vulnerable to: GO-2025-3487 / GHSA-hcg3-q754-cr77","Warn: Project is vulnerable to: GO-2021-0061 / GHSA-r88r-gmrh-7j83","Warn: Project is vulnerable to: GO-2022-0956 / GHSA-6q6q-88xp-6f2r","Warn: Project is vulnerable to: GO-2020-0036 / GHSA-wxc4-f4m6-wwqv"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 2 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T21:03:44.225Z","repository_id":50974717,"created_at":"2025-08-18T21:03:44.225Z","updated_at":"2025-08-18T21:03:44.225Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28431118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T18:57:19.464Z","status":"ssl_error","status_checked_at":"2026-01-14T18:52:48.501Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":"2026-01-14T18:59:47.283Z","updated_at":"2026-01-14T18:59:48.070Z","avatar_url":"https://github.com/flyteorg.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# protoc-gen-doc\n\n[![Travis Build Status][travis-svg]][travis-ci]\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 get -u github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc`\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\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\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 /protos/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 by `:`.\nFor 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[travis-svg]:\n    https://travis-ci.org/pseudomuto/protoc-gen-doc.svg?branch=master\n    \"Travis CI build status SVG\"\n[travis-ci]:\n    https://travis-ci.org/pseudomuto/protoc-gen-doc\n    \"protoc-gen-doc at Travis CI\"\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyteorg%2Fprotoc-gen-doc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyteorg%2Fprotoc-gen-doc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyteorg%2Fprotoc-gen-doc/lists"}