├── .github └── workflows │ └── go-test.yml ├── LICENSE ├── README.doc.md ├── README.dump.md ├── README.json.md ├── README.md ├── cmd ├── protoc-gen-doc │ └── main.go ├── protoc-gen-dump │ └── main.go └── protoc-gen-json │ └── main.go ├── go.mod ├── go.sum ├── templates ├── common.html ├── filemap.xml ├── index.html ├── service.html └── tmpl.html ├── tmpl ├── filemap.go ├── filemap_test.go ├── generator.go ├── json.go ├── util.go └── util_test.go └── util ├── all.go ├── debug.go ├── gen.go ├── resolver.go ├── resolver_test.go ├── testdata ├── resolve │ └── world │ │ └── region │ │ ├── building.proto │ │ ├── hello.proto │ │ └── human.proto └── resolver.json ├── util.go └── util_test.go /.github/workflows/go-test.yml: -------------------------------------------------------------------------------- 1 | name: Go test 2 | on: [push] 3 | jobs: 4 | test: 5 | name: Test 6 | runs-on: ubuntu-latest 7 | steps: 8 | - name: Set up Go 1.13 9 | uses: actions/setup-go@v1 10 | with: 11 | go-version: 1.13 12 | id: go 13 | - name: Check out code into the Go module directory 14 | uses: actions/checkout@v1 15 | - name: Get dependencies 16 | run: go get -v -t -d ./... 17 | - name: Build 18 | run: go build -v ./... 19 | - name: Test 20 | run: go test -race -v ./... 21 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015 Sourcegraph, Inc. 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining 4 | a copy of this software and associated documentation files (the 5 | "Software"), to deal in the Software without restriction, including 6 | without limitation the rights to use, copy, modify, merge, publish, 7 | distribute, sublicense, and/or sell copies of the Software, and to 8 | permit persons to whom the Software is furnished to do so, subject to 9 | the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be 12 | included in all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 15 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 16 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 17 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 18 | LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 19 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 20 | WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.doc.md: -------------------------------------------------------------------------------- 1 | # protoc-gen-doc 2 | 3 | `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. 4 | 5 | ## Installation 6 | 7 | First install Go and Protobuf itself, then install the plugin using go get: 8 | 9 | ``` 10 | go get -u sourcegraph.com/sourcegraph/prototools/cmd/protoc-gen-doc 11 | ``` 12 | 13 | ## Usage 14 | 15 | Simply invoke `protoc` with the `--doc_out` command-line parameter: 16 | 17 | ``` 18 | protoc --doc_out="" input.proto 19 | protoc --doc_out=":" input.proto 20 | ``` 21 | 22 | Where `` is a comma-seperated list of `key=value,key2=value2` options (which are listed in detail below). For example: 23 | 24 | ``` 25 | protoc --doc_out="doc/" file.proto 26 | ``` 27 | 28 | Would produce documentation for `file.proto` inside the `doc/` directory using the template `templates/tmpl.html` HTML template file. 29 | 30 | ## Options 31 | 32 | | Option | Default | Description | 33 | |----------------|-----------------------------|--------------------------------------------------------------------| 34 | | `template` | `templates/tmpl.html` | Input `.html` `html/template` template file to use for generation. | 35 | | `root` | (current working directory) | Root directory path to prefix all generated URLs with. | 36 | | `filemap` | none | A XML filemap, which specifies how output files are generated. | 37 | | `dump-filemap` | none | Dump the executed filemap template to the given filepath. | 38 | | `apihost` | none | (grpc-gateway) API host base URL (e.g. `api.mysite.com`, no colons in value) | 39 | | `conf` | none | Comma-separated text configuration file with these very options. | 40 | 41 | The `template` and `filemap` options are exclusive (only one may be used at a time). 42 | 43 | ## Templates 44 | 45 | Template files are standard Go `html/template` files, and as such their documentation can be found [in that package](https://golang.org/pkg/html/template). 46 | 47 | ## File Maps 48 | 49 | In 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. 50 | 51 | Say for example that we wanted to produce documentation for three gRPC services, all of which are declared inside of a `organization/services.proto` file: 52 | 53 | - "Producer" -> `out_dir/organization/service-producer.html` 54 | - "Consumer" -> `out_dir/organization/service-consumer.html` 55 | - "Trader" -> `out_dir/organization/service-trader.html` 56 | 57 | And also an `out_dir/index.html` file which will link to the three services. 58 | 59 | In 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: 60 | 61 | ``` 62 | 63 | 64 | 65 | path/to/target.proto 66 | path/to/output.html 67 | 68 | a.tmpl 69 | b.tmpl 70 | 71 | 72 | myKey1myValue1 73 | myKey2myValue2 74 | 75 | 76 | 77 | ... 78 | 79 | 80 | ``` 81 | 82 | Where `