search

pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.66k stars 463 forks source link

Cannot set the template filename when using the buf remote plugin #513

Closed ZeeD closed 1 year ago

ZeeD commented 1 year ago

I use buf with your plugin to generate documentation. In the buf.gen.yaml I've set opt: 'markdown.tmpl,doc.md' to use a custom template.

Using a local copy of your plugin (obtained via go get) I can generate the documentation succesfully.

I saw that it's possible to use remote plugins with buf, but with this version it seems I cannot set the template name, and I got the error: Failure: plugin "buf.build/community/pseudomuto-doc:v1.5.1" exited with non-zero status 1: 2023/03/29 09:06:28 open markdown.tmpl: no such file or directory

This is my "new" buf.gen.yaml (the commented out lines were present in the working configuration):

version: v1
managed:
  enabled: true
plugins:
  - plugin: buf.build/community/pseudomuto-doc
#  - name: doc
#    path: bin/protoc-gen-doc
    out: docs
    opt: 'markdown.tmpl,doc.md'

I've tried to set also an absolute path, or different relative paths... but it seems it is not recognized.

amenzhinsky commented 1 year ago

@ZeeD the trick is remote plugins work a bit differently as you might expect, buf generate doesn't download and call protoc-gen-doc, instead it sends proto file contents along with opts to buf.build and receives the output from the server.

ZeeD commented 1 year ago

uhm... apart from the "security" implications (a schema is not exactly PII, but I'm not sure I can share it outside my job without approval) then is there a way to tell buf to also upload some additional files (like my markdown.tmpl)? Is this something related directly to your project or is this something I need to address with buf developers?

amenzhinsky commented 1 year ago

For sure this is not a protoc-gen-doc issue.

No, it uploads proto only and most likely won't accept anything else.

TBH this is not a buf's issue neither, it works as it supposed to, in case you don't want to share your proto definitions, you should fall back to local plugins.

ZeeD commented 1 year ago

closing as this is not a protoc-gen-doc issue