Feature/separate files

[willchang]

Hello! I've come across a use case where it would be nice to have one output file per input file. I'm setting up a static documentation site for Proto files and the UX is better when the output mirrors the input instead of having them grouped together on one page (regardless of using source_relative or not).

Summary

This PR adds support for a separate_files flag which outputs one file per input file instead of grouping input files into one output file.

Usage:

protoc --doc_out=. --doc_opt=markdown,md,source_relative,separate_files hello.proto world.proto nested/foo.proto

This would output:

hello.md
world.md
nested/foo.md

Notes on Behaviour

• The value passed in for the second parameter (the name of the output file) is used as the extension of each output file. For example, if you pass md like in the example above, the output files would be <filename>.md.
• This flag can be used with source_relative or without, it does not change source_relative's functionality.

Testing it Out

I was testing using this command from the repo root:

make build && protoc --plugin=bin/protoc-gen-doc \
--proto_path=<PATH_TO_PROTO_FILES_ROOT>\
--doc_out=. \
--doc_opt=markdown,md,source_relative,separate_files \
<PATH_TO_PROTO_FILES_ROOT>/**/*.proto

Additional Notes on Implementation

I've kept the same convention of adding another parameter to the --doc_opt list. I can foresee this becoming hard to manage in the future since a) parameters are mapped to indices which makes the code ugly as you gain more parameters and b) usage-wise you must specify default for previous parameters you may not care about. However, I didn't want to make assumptions on the grander vision of this API (and also introduce a lot of out-of-scope changes) so I just followed the convention.

I'm an iOS developer and Go is a little foreign to me, so please feel free to give feedback on conventions or anything else that doesn't seem to fit quite right. Thanks!

[adlion]

Is this feature available on latest

Thank you for your work on this library.

[willchang]

Is this feature available on latest

Thank you for your work on this library.

Thanks @adlion, it needs to be approved first by someone with write access. cc: @pseudomuto