search

pseudomuto / protoc-gen-doc

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

buf skips 'duplicate' files when invoked with multiple proto files #449

Open alexanderjophus opened 3 years ago

alexanderjophus commented 3 years ago

I have the following structure

proto
- gen
  - doc
  - js
- idl
  - service1
    - service1.proto
  - service2
    - service2.proto

I have the following buf.yaml

version: v1beta1
name: buf.build/company/project
deps:
  - buf.build/beta/googleapis
build:
  roots:
    - proto/idl

and buf.gen.yaml

version: v1beta1
plugins:
  - name: grpc-web
    out: proto/gen/js
    opt: import_style=commonjs+dts,mode=grpcwebtext
  - name: doc
    out: proto/gen/doc
    opt: markdown,proto.md

The following error occurs

Warning: Duplicate generated file name "proto.md". Buf will continue without error here and drop the second occurrence of this file, but please raise an issue with the maintainer of the plugin.

With the js plugin (and go/swagger/others) a subdirectory is created per service and the service.js or service.pb.gois placed within that directory, however with the doc plugin no subdirectory is made leading to the duplicate files above.

Is there an option to use the subdirectory the .proto file was found in as the output like the other plugins?

Gr1N commented 3 years ago

@trelore you need to specify strategy all:

version: v1beta1
plugins:
  - name: doc
    out: gen/doc
    strategy: all
alexanderjophus commented 3 years ago

Thanks! That works as a workaround, however as far as I can tell it combines all the md files into one unordered list, as we have a lot of microservices it'd be amazing to have them all in their own directory or saved as individual files.

nghiant3223 commented 8 months ago

Thanks! That works as a workaround, however as far as I can tell it combines all the md files into one unordered list, as we have a lot of microservices it'd be amazing to have them all in their own directory or saved as individual files.

This setup works for me:

-- buf.gen.yaml

version: v1
plugins:
  - name: doc
    out: docs
    opt: markdown,README.md,source_relative
    strategy: all

The documentation of each service resides on its own directory:

├── docs
│   ├── cards
│   │   └── v1
│   │       └── README.md
│   ├── checkout
│   │   └── v1
│   │       └── README.md