Skip to content

Include file reference to types #521

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.

Sign up for GitHub

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

Closed
TristanFloch wants to merge 11 commits into from
Closed

Include file reference to types #521

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
af45a08
Testing adding a new parameter which allows output files to map 1:1 t…
willchang Aug 5, 2022
c3514c0
Cleaned up checking for additional params as well as processing of fi…
willchang Aug 18, 2022
4109748
Updated documentation and readme.
willchang Aug 18, 2022
3bb4bbd
Added tests for parsing separate_files param and also expected files …
willchang Aug 18, 2022
4744571
Restored condition to check for number of parameters above expected n…
willchang Aug 19, 2022
b1c702f
Resolve file of types for message fields
Jul 5, 2023
c416bc8
Resolve file of request and response types in service methods
Jul 11, 2023
640e3cd
Remove '.proto' suffix in type file value
Jul 11, 2023
5987e9d
Generate mutli paged html documentation using a new template
Jul 12, 2023
fc7ad5c
Examples: include Booking.proto in Customer.proto
Jul 12, 2023
7e9cb6f
Examples: resolve file paths in multi page template
Jul 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,9 @@ PROTOS_DIR=$(EXAMPLE_DIR)/proto
EXAMPLE_CMD=bin/protoc --plugin=bin/protoc-gen-doc \
-Ithirdparty -Itmp/googleapis -Iexamples/proto \
--doc_out=examples/doc
EXAMPLE_CMD_MULTI_PAGE=bin/protoc --plugin=bin/protoc-gen-doc \
-Ithirdparty -Itmp/googleapis -Iexamples/proto \
--doc_out=examples/doc-multi-page

DOCKER_CMD=docker run --rm \
-v $(DOCS_DIR):/out:rw \
Expand Down Expand Up @@ -44,6 +47,7 @@ build/examples: bin/protoc build tmp/googleapis examples/proto/*.proto examples/
@$(EXAMPLE_CMD) --doc_opt=json,example.json:Ignore* examples/proto/*.proto
@$(EXAMPLE_CMD) --doc_opt=markdown,example.md:Ignore* examples/proto/*.proto
@$(EXAMPLE_CMD) --doc_opt=examples/templates/asciidoc.tmpl,example.txt:Ignore* examples/proto/*.proto
@$(EXAMPLE_CMD_MULTI_PAGE)/html --doc_opt=examples/templates/html-multi-page.tmpl,html,source_relative,separate_files:Ignore* examples/proto/*.proto

##@: Dev

Expand Down
14 changes: 13 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,25 @@ example](examples/gradle).
The plugin is invoked by passing the `--doc_out`, and `--doc_opt` options to the `protoc` compiler. The option has the
following format:

--doc_opt=<FORMAT>|<TEMPLATE_FILENAME>,<OUT_FILENAME>[,default|source_relative]
--doc_opt=<FORMAT>|<TEMPLATE_FILENAME>,<OUT_FILENAME>[,default|source_relative][,default|separate_files]

The format may be one of the built-in ones ( `docbook`, `html`, `markdown` or `json`)
or the name of a file containing a custom [Go template][gotemplate].

### `source_relative`

If the `source_relative` flag is specified, the output file is written in the same relative directory as the input file.

### `separate_files`

If the `separate_files` flag is specified, there will be one file outputted per input file and the second parameter,
`<OUT_FILENAME>`, will be used as the extension of the outputted files.

For example, the following will result in the outputted files `foo.md` and `bar.md` since `md` is passed as the second parameter.
```
--doc_opt=markdown,md,source_relative,separate_files foo.proto bar.proto
```

### Using the Docker Image (Recommended)

The docker image has two volumes: `/out` and `/protos` which are the directory to write the documentation to and the
Expand Down
3 changes: 3 additions & 0 deletions cmd/protoc-gen-doc/flags.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,9 @@ protoc --doc_out=. --doc_opt=custom.tmpl,docs.txt protos/*.proto
EXAMPLE: Generate docs relative to source protos
protoc --doc_out=. --doc_opt=html,index.html,source_relative protos/*.proto

EXAMPLE: Generate docs relative to source protos, one output file per input file
protoc --doc_out=. --doc_opt=html,html,source_relative,separate_files protos/*.proto

See https://github.com/pseudomuto/protoc-gen-doc for more details.
`

Expand Down
Loading