Support for map and oneof field

[nicholas-presien]

Hey @markvincze

Love your work with sabledocs, I think it's currently one of the better open sources gRPC and protocol buffer documentation generator out there.

I was trying Sabledocs out and found that map field and oneof field are not being visualise correctly in the generated HTML docs. Is there any way to get those field showing correctly in the generated HTML doc?

Would love to contribute if this functionality is not in yet too!

[markvincze]

Hi @nicholas-presien, Thanks for reporting the issue! Maps are supposed to work, could you send the Proto definition of your type with which the Map is not showing up correctly? Then I can check what is going wrong. Or if you're interested, this is the part where we use some heuristics to try to determine whether a field has a map type or not, maybe this logic is not complete and not working for your example for some reason: https://github.com/markvincze/sabledocs/blob/main/src/sabledocs/proto_descriptor_parser.py#L142

Oneof support is indeed missing at the moment, and that's the one major feature left before I'd like to release version 1.0. I already have a branch with working support for parsing oneof information from the Proto contract and including it in the data model, and I have to finish working on the UI part to include it in the rendered output. I'll send an update in this issue when there is progress.

[markvincze]

Ah, right, I see that maps are not working in the demo documentation either, for example in this type: https://markvincze.github.io/sabledocs/demo/google.datastore.v1.html#message-google.datastore.v1.GqlQuery, named_bindings is supposed to be a map. I'll investigate this.

[markvincze]

@nicholas-presien,

Support for maps is fixed in #48, a dev version was released: https://pypi.org/project/sabledocs/0.11.589.dev0/, could you check if this works for you?

[nicholas-presien]

@markvincze

Yep tested with my own generated .pb file and the fix works! Thanks for the quick fix.

Let me know if there's an update on oneof support.

[markvincze]

@nicholas-presien I implemented support for displaying oneofs, you can see an example of it on the demo site: https://markvincze.github.io/sabledocs/demo/google.datastore.v1.html#message-google.datastore.v1.CommitRequest

It's included in the latest 0.11.656 release.

[nicholas-presien]

@markvincze

I've tested 0.11.656 release and oneof field are showing up correctly. I did however notice another bug where optional fields are now showing as oneof field. This is technically correct from a protobuf implementation level as optional field are technically oneof, but it's slightly confusing when the docs shows it as a oneof field instead of optional field

[markvincze]

@nicholas-presien, Thanks for flagging this, that's not intended, I'll adjust the logic to exclude optionals from this.

[markvincze]

@nicholas-presien Should be fixed in 0.11.670, if you can give it a try, it'd be appreciated!

[nicholas-presien]

@markvincze sorry was the late reply and happy new year!

Tested 0.11.671 and it does resolve the issue. Thanks!