Refactor documentation protobuf object tooling

[geel9]

With #635, protobuf fields which are not required are marked with the options.optional attribute (FQN is services.options.optional).

This attribute exists solely for documentation generation -- when generating proto docs, we should label optional fields as such.

[geel9]

This is going to be more work than anticipated... protoc-gen-doc doesn't presently handle custom field options, meaning we don't have any way of knowing if a field has the optional option set.

This issue is discussed in pseudomuto/protoc-gen-doc#425

We have a few options:

• Fix protoc-gen-doc to enable custom option exports
  • Would require a fair amount of work... protoc stuff gets pretty complicated.
  • To do it right would require we do this for fields, messages, files, etc. -- not just fields.
  • We don't need all the information that could/should be exported in a full solution; we only need to know if option 60,000 is present on a field.
• Use protokit to create custom JSON exporter plugin to replace protoc-gen-doc
  • In line with ultimate plan to use protoc-gen-doc's JSON exporter, instead of its Markdown exporter, to enable higher-fidelity tooling around our protobuf objects in docs.
  • I already got this working -- I'm able to use it to export an array of which options are present on a field, which is the only information we need.
  • Would require us to publish and maintain a go package for this plugin.

[tmarkovski]

@geel9 Do you need help setting up the Go plugin / publishing repo?

@sethjback

[geel9]

Yeah, I've never actually worked in Go -- writing the actual plugin itself isn't the issue, so much as making it easy to plug into our GitHub actions. Not sure how the project should be structured, how to make it available via go get, etc.

[tmarkovski]

It would likely be published in a repo of our own and used as a dependency using go get, same way we do for okapi and sdk. Go references are direct GitHub repos.