search

pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.59k stars 462 forks source link

feat: source_relative #450

Closed Rossiar closed 2 years ago

Rossiar commented 2 years ago

adds support for generating the docs in the folder relative to the proto source path. If there are multiple directories containing proto files, adding the option --doc_out=markdown,index.md,source_relative will generate the file index.md under each of the proto directories with the documentation for the files in that directory. This PR satisfies https://github.com/pseudomuto/protoc-gen-doc/issues/449 and is a very lazy copy of https://github.com/pseudomuto/protoc-gen-doc/pull/399, which is simply out of date and I wasn't smart enough to fixup.

@pseudomuto it would be great to merge this as the source_relative opt is an accepted option for protoc-gen-go and will also allow this plugin to be used nicely with the lovely buf generate

pseudomuto commented 2 years ago

Hey @Rossiar thanks for the PR! In general this looks good to me. I ran the tests and examples locally and things look good 👍

Can you document the option in README.md and add an entry to the CHANGELOG.md file? Once that's done, I'll get this merged and cut a new release.

Rossiar commented 2 years ago

@pseudomuto all done

pseudomuto commented 2 years ago

v1.5.0 has been released (docker image will take a little longer). Thanks again for the PR!

kd7lxl commented 2 years ago

Have you got this to work with buf generate? I tried a few permutations of what I thought were the right options and got errors each time.

Rossiar commented 2 years ago

@kd7lxl can you open a new issue? There are a few examples in https://github.com/pseudomuto/protoc-gen-doc/issues/449 (which we can actually close @pseudomuto since I think this PR solved it) to help you debug

houseofmercy-github commented 1 year ago

For the benefit of anyone else trying out this plugin with buf who may be unfamiliar with the relationship between the buf.gen.yaml settings and the corresponding protoc-gen-doc options, here is what worked for me:

version: v1
plugins:
  - name: doc
    out: ./gen/doc
    opt: html,index.html,source_relative

Note here since name: doc is specified the plugin is passed --doc_opt=html,index.html,source_relative.

If you naively try to specify only the source_relative option like I first did e.g.

version: v1
plugins:
  - name: doc
    out: ./gen/doc
    opt: source_relative                   <--- don't do this it will fail

you will see Invalid parameter: source_relativebecause ParseOptions won't see a ,

The message isn't wrong but it's confusing and could be improved. It would have saved me some time had it given the description in the comment a few lines earlier e.g.

Invalid parameter: source_relative  
The parameter --doc_opt must be of the format
<TYPE|TEMPLATE_FILE>,<OUTPUT_FILE>[,default|source_relative]:<EXCLUDE_PATTERN>,<EXCLUDE_PATTERN>*.