Add UML generation, cleanup + add documentation

[MikeSmithEU]

Why?

Greatly improves upon the following guiding principles going forward:

• Annotation over documentation. Documentation should relate to code where possible.
• Pragmatism. We want to deliver maximum benefit with minimal effort, incrementally.

(Ref: https://github.com/ebu/benchmarkstt/wiki/Principles)

Changes and additions

• [x] Makefile: use environment python if available, otherwise use python3
• [x] Makefile: ensure pip is installed (in some cases needed for development, avoids user confusion)
• [x] cleanup code
• [x] add automatic UML diagrams to documentation
• [x] custom autodoc templates
• [x] add sphinx mermaid autoclassmemberdiagram directive
• [x] refactor code:
  • [x] group cli and api entrypoints in their respective packages
  • [x] use more descriptive names for Base classes (Normalizer, Differ, etc.)

Chronologic todos

• [x] Makefile: use environment python if available, otherwise use python3
• [x] Makefile: ensure pip is installed (in some cases needed for development, avoids user confusion)
• [x] removed an unused import from src/benchmarkstt/cli.py
• [x] adds additional documentation (per-package docstrings)
• [x] converts benchmarkstt.benchmark from a module to a namespace
• [x] make the magic per-package api.py and cli.py "private" (moved to _api.py and _cli.py)
• [x] autogenerate PlantUML files per package
• [x] add (simplified) custom PlantUML class diagrams per package to docs
• [x] implement a PlantUML renderer to SVG
• [x] link all packages and classes to proper documentation pages
• [x] optimize PlantUML svg renderer
• [x] omit _uml.py from code coverage checks
• [x] add uml generation to Makefile
• [x] generate uml on docs generation
• [x] document plantuml.jar requirement for generating uml graphs
  • [x] add in comments in _uml.py
  • [x] add explanation about missing plantuml.jar and where to download if plantuml call fails
• [x] docs/CONTRIBUTING.rst
  • [x] emphasize not pushing straight to master branch
  • [x] add info about license of code added by contributors
• [x] Remove the plantuml.jar dependency (use http://www.gravizo.com/ )
• [x] Support .. plantuml: or .. gravizo: ReStructuredText in documentation (https://github.com/MikeSmithEU/sphinxcontrib-gravizo)
• [x] cleanup all plantuml -> svg code
• [x] update docs to use .. gravizo:
• [x] find work-around for too long request uri's for the bigger UML diagrams
• [x] add custom autodoc templates
• [x] update sphinx to latest
• [x] automate mermaid structure graphs
• [x] add members to autodocgraph (custom sphinx directive based on existing mermaid)
• [x] completely move to mermaid
• [x] cleanup all gravizo
• [x] cleanup docs/conf.py
• [x] generate svgs on server side for documentation
• [x] factor out yarn usage, simplify docs run (using pynpm)
• [x] add changelog

[MikeSmithEU]

Generated docs available at https://benchmarkstt.readthedocs.io/en/uml-schema (hidden)

[MikeSmithEU]

Hey Mike! Thanks for these changes, the diagrams are great! It's good to have you back :)

I've added a few comments, and a couple of extras here:

• I didn't have PlantUML installed, so I think installation instructions should be added to development.rst, under "Building the Documentation". You could mention it's available via homebrew (brew install plantuml) or via https://plantuml.com/download.
• Since the UML files are automatically generated, I wonder whether they should be included in git? I think I'd prefer to see docs/_static/uml in the .gitignore instead (and create the uml directory in the Makefile)

It is my intention to remove the plantuml -> svg from this PR. I agree that the uml directory should be .gitignored. I am currently having issues generating the svg's on readthedocs.org though, and have spent quite a lot of time looking for alternate solutions. The only reasonable one I've found thus far is http://www.gravizo.com/

Simply documenting how to install plantuml is not feasibly imho (or at least, I won't do it), as it would need to cover Windows, OSX and Linux targets, making sure a proper version of java is installed and provide ongoing support for this.

I've now converted this PR to draft until I can implement that, but it gets me to quite a side tangent as this is far outside the scope of this project, and the cleanest is writing a new sphinx plugin for this. I am really short on free time at the moment so this is appended to my long todo list. To be continued...

[MikeSmithEU]

@danielthepope Embed PlantUML, DOT, etc. diagrams in documentation using Gravizo now supported, and separated it from benchmarkstt.

https://pypi.org/project/sphinxcontrib-gravizo/

Examples Inline graph, show as png:

.. gravizo:: png
    @startuml
    Alice -> Bob: Authentication Request
    Bob --> Alice: Authentication Response

    Alice -> Bob: Another authentication Request
    Alice <-- Bob: Another authentication Response
    @enduml

Load from a file, show as svg:

.. gravizo:: ./path/to/graph.puml svg

[MikeSmithEU]

Docs build of uml files is now completely separated. Gravizo plugin moved to sphinxcontrib organization and added as a dependency for docs. All svg- and puml-files are no longer polluting this repository.

Since there are a few big graphs that cannot be directly generated by a GET-request to Gravizo (request uri too long as per HTTP RFC) I still need to implement a work-around for that.

[MikeSmithEU]

That's very cool how you've managed to make the diagrams generate in the front end! I wonder if I'm doing something wrong though, or maybe I've spotted a problem?

After generating the docs, running cddocs/build/html;python3 -m http.server I go to http://localhost:8000/modules/benchmarkstt.api.html.

A diagram doesn't show up and there's an error in the browser's console

Uncaught Error: Parse error on line 1:
classDiagram
------------^
Expecting 'NEWLINE', got 'EOF'

Sorry for the late reply, I've been indisposed for a couple of days.

Indeed, this is because for those modules there are no public classes available, so it returns an "empty" classDiagram, i.e. an unexpected EOF. I will have a look if I can either pre-check this (probably will result in messy code fixes), or contribute the functionality to "skip if empty" to the original sphinxcontrib repository (seems the better idea, but does not assure acceptance by the repo maintainer(s)). I feel this can be ignored for the time being as it does not really affect the users of the documentation.

[MikeSmithEU]

I feel this can be ignored for the time being as it does not really affect the users of the documentation.

Fair enough, that's fine then.

I've just realised that because you're using this new way of generating UML, you no longer need the autogen folder, so you can delete the docs/_static/autogen/.keep file.

After that, this will be good to merge 😄

Good catch, I've been experimenting with generating the svg's server side though, and thought it might still be useful (turns out even then it's not needed). Cleaned them up in the latest commit.

The svg generating server side is quite problematic it seems. It spews all kinds of weird syntax errors on the mermaid code (which does render properly using the client-side renderer or mermaid live preview). Some are related to html escaping (which I solved locally), others I haven't been able to figure out yet. Because I spent way too much time on it already I will keep it as-is. (edit: turns out I was using the wrong package, mermaid.cli != @mermaid-js/mermaid-cli)

If we can agree on the usage of yarn, I suggest this to be the ready-to-merge PR, pending approval from you. edit: Factored out yarn

Edit: let's consider this a near-ready-to-merge PR, there are a few issues I still need to solve. I.e. the textwrapping of the __init__ arguments in the diagram shows some issues that I need to fix. And there is some self-referencing arrows in the diagrams that shouldn't be there. Both these issues should be quite easy to fix (requiring much less time and effort than any of the experiments I've done before to reach this point). When these two remaining issues are taken care of (by the end of the week for sure), (edit: fixed) I will merge once you approve of my changes.

[MikeSmithEU]

@danielthepope This should be ready to merge once you approve...

[MikeSmithEU]

Factored out yarn