Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sourcegraph/prototools

documentation generator & other tools for protobuf/gRPC
https://github.com/sourcegraph/prototools

Last synced: 3 months ago
JSON representation

documentation generator & other tools for protobuf/gRPC

Awesome Lists containing this project

README 

        
# protoc-gen-doc



`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.



## Installation



First install Go and Protobuf itself, then install the plugin using go get:



```

go get -u sourcegraph.com/sourcegraph/prototools/cmd/protoc-gen-doc

```



## Usage



Simply invoke `protoc` with the `--doc_out` command-line parameter:



```

protoc --doc_out="" input.proto

protoc --doc_out=":" input.proto

```



Where `` is a comma-seperated list of `key=value,key2=value2` options (which are listed in detail below). For example:



```

protoc --doc_out="doc/" file.proto

```



Would produce documentation for `file.proto` inside the `doc/` directory using the template `templates/tmpl.html` HTML template file.



## Options



| Option         | Default                     | Description                                                        |

|----------------|-----------------------------|--------------------------------------------------------------------|

| `template`     | `templates/tmpl.html`       | Input `.html` `html/template` template file to use for generation. |

| `root`         | (current working directory) | Root directory path to prefix all generated URLs with.             |

| `filemap`      | none                        | A XML filemap, which specifies how output files are generated.     |

| `dump-filemap` | none                        | Dump the executed filemap template to the given filepath.          |

| `apihost`      | none                        | (grpc-gateway) API host base URL (e.g. `api.mysite.com`, no colons in value)   |

| `conf`         | none                        | Comma-separated text configuration file with these very options.   |



The `template` and `filemap` options are exclusive (only one may be used at a time).



## Templates



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).



## File Maps



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.



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:



- "Producer" -> `out_dir/organization/service-producer.html`

- "Consumer" -> `out_dir/organization/service-consumer.html`

- "Trader"   -> `out_dir/organization/service-trader.html`



And also an `out_dir/index.html` file which will link to the three services.



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:



```



    

        path/to/template.html

        path/to/target.proto 

        path/to/output.html

        

            a.tmpl

            b.tmpl

        

        

            myKey1myValue1

            myKey2myValue2

        

    

    

        ...

    



```



Where `` and `` paths are relative to the XML filemap directory, `` paths are relative to the output directory, and `` paths are relative to `--proto_path` directories.



Thus we would write:



```



    

    

        index.html

        index.html

    



    

    

        service.html

        organization/services.proto

        organization/service-producer.html

        

            ServiceProducer

        

    

    

        service.html

        organization/services.proto

        organization/service-consumer.html

        

            ServiceConsumer

        

    

    

        service.html

        organization/services.proto

        organization/service-trader.html

        

            ServiceTrader

        

    



```



As 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:



```



    

    

        index.html

        index.html

    



{{$serviceTemplate := "service.html"}}

{{range $f := .ProtoFile}}

    {{range $s := .Service}}

        

            {{$serviceTemplate}}

            {{$f.Name}}

            {{dir $f.Name}}/{{$s.Name}}{{ext $serviceTemplate}}

            

                Service{{$s.Name}}

            

        

    {{end}}

{{end}}



```



Which is to say: for every service type (`range $s := .Service`) in every protobuf input file (`range $f := .ProtoFile` and `{{$f.Name}}`) 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 `` is executed pass along a map with the given keys/values (the service template can then selectively render _just that service type_).



For debugging purposes, you can use the `dump-filemap` option which will execute the template and dump the resulting XML out to a file.



## Issues



If you run into trouble or have questions, please [open an issue](https://github.com/sourcegraph/prototools/issues/new).