search

pseudomuto / protoc-gen-doc

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

Use full path for cross file links #444

Open renjiexu opened 3 years ago

renjiexu commented 3 years ago

Hi team,

In our company, we're using namespace such as following:

company
├── account
│   └── rpc
│       └── v1
│           └── account_api.proto
├── webhook
│   └── v1
│       └── webhook.proto
|       └── api.proto

instead of generating one html for all the *.proto, we generate one for each namespace:

company
├── account
│   └── rpc
│       └── v1
│           └── index.html
├── webhook
│   └── v1
│       └── index.html

However, if webhook.proto refers a type in account_api.proto, the link would not work. This PR would address the problem, confirmed it's working for me, would like your thoughts on this before adding specs.

(might be able to solve the request of https://github.com/pseudomuto/protoc-gen-doc/issues/406)

Thanks, Renjie

alkasm commented 2 years ago

Bumping this, would be really interested here as well. We have way too many protos to comfortably fit on one page, so the per-folder or per-package approach with cross-linking would be perfect.

renjiexu commented 2 years ago

@alkasm good to know, I have a working solution for HTML/markdown in my forked version, will try to fix the unitest so we could have a clean PR to merge

alkasm commented 2 years ago

I think I found an issue with the generated links for nested message definitions. If you have

message Outer {
    message Inner { }
    Inner inner = 1;
}

Then protoc-gen-doc correctly makes the inner field link to #pkg.Outer.Inner, but this pr instead links to #/full/path/pkg.Outer.Inner. Either the initial # needs to be removed, or the full path needs to be removed when they're in the same file.