Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Feature/separate files #492

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

willchang
Copy link

@willchang willchang commented Aug 18, 2022

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!

plugin.go Outdated Show resolved Hide resolved
plugin.go Outdated Show resolved Hide resolved
…umber (now 4). Also changed for loop to be more idiomatic.
@willchang willchang force-pushed the feature/separate_files branch from d0ef57b to 38c90d2 Compare August 19, 2022 16:54
@adlion
Copy link

adlion commented Jan 1, 2024

Is this feature available on latest

Thank you for your work on this library.

@willchang
Copy link
Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants