Update architecture documentation

[arnecls]

The current architecture documentation (read the docs RST files) are still from the 0.3.x era.
Change them according to the new structure and add FAQ about architecture by plugin developers.

• High level architecture of message passing
• Explaining the "stream width" (ModulatorQueues)
• Purpose of the different plugin types
• Components, purposes and type hierarchy
• Basic implementation examples

Update - Open tasks before v0.5.0 release:

• Finalise release notes
• Describe Metadata handling in Terminology
• Add Guide to update plugins from v0.4 to v0.5
• Run gollum benchmark of v0.4 VS v0.5
• Add docs for metrics
• Add docs for healthchecks
• Describe buffered- and batched-producer components (optional)

[ppar]

For the end user docs, rIght now there's a lot of duplication between comments in the source code and the .rst files (namely plugins' config settings), and also between the .rst files themselves (a lot of them begin with the same boilerplate text).

How can we avoid this? Can we autogenerate some/all of the docs from the sources and use some include mechanism for the repeated parts?

A visual architecture overview would be really useful for the end user as well, to explain how the plugins do (and don't) interact, and where to implement specific functionality (e.g. that messages can only be modified at the consumer stage and not during routing and the retry logic (#99) rationale behind this).

[arnecls]

The rst files are generated by an internal tool from the source code comments.

[ppar]

Which one and how?

I couldn't find any, the top level makefile doesn't have a target for this and docs/Makefile just seems to generate docs from the .rsts

[arnecls]

It's called gollum-docs and it's one big, ugly file with a lot of unchecked assumptions in it.
It's on the list of the "things-to-clean-up-and-release".
Probably a good thing to do along with this task.