Add protoc plugin to generate schema UML diagram in documentation

[malisas]

This PR adds a protoc plugin to generate a schema UML diagram in the documentation.

The svg is saved as doc/source/_build/generated_images/schema_uml.svg, which is then used in doc/source/schemas/index.rst to be processed by sphinx and turned into schemas/index.html.

Addresses #402

TODOS:

1. I don't actually use the --custom_out protoc option in protobuf-uml.py. But removing it makes protoc complain Missing output directives.
2. If desired, I can add back links to the schema source code (when you click on individual clusters).

Thanks for your patience!

[malisas]

Screenshot of what schemas/index.html looks like:

[david4096]

This is really cool! I like your proposed feature. I'd also like to remove the Google stuff from the diagram, which is what I think appears on the right. It seems like we will need to add the requirement of having installed the graphviz binary if you want to make them locally.

[malisas]

Thanks @david4096 for the original recommendation for making it a plugin, by the way!

Oh woops, I thought I got rid of the Google stuff but I'll take a look at it again.
I added graphviz to the python/dev-requirements.txt file -- I think that should be enough to make the docs locally...?

[david4096]

@malisas my bad, you're right that is G2P off to the right on the diagram!

I had to add graphviz to the environment.yml and updated the version of sphinx. You can view the result here: http://schemas.readthedocs.io/en/latest/schemas/index.html

If it were at least clickable to view image, that would be great. Perhaps also bring down the image size so that the zoomed image is navigable. It's too big to easily scroll around right now. I think it also needs a line legend, a title, and some reference to the protocol version. All of the orange lines get a bit confusing, especially when so many things are ontology terms. Maybe we could cram the type in the message declaration. Those are feature requests for the future.

Anyhow this is great! It makes something pretty complicated accessible visually. Definitely makes me think we could generate images for within each service as well! I'd like to get this merged ASAP, at which point you're welcome to add features (like hyperlinks inside the svg).

[malisas]

Ok! Made some of those changes, enough to be merge-able I think.

Eventually I'll see if I can add the cluster links, a line legend, a reference to the protocol version, and see if I can place the type into the message declaration of each table.

[malisas]

Ok, updated the README.