Provide real documentation
Instead of a single bloated readme, we should provide a real documentation as this project grows.
We should especially add information about how to use this project:
- What can be configured
- How can something be configured
- How to configure the project to be adjusted to your needs, with examples to understand the possibilities.
Of course this involves the following steps:
-
Migrate readme to documentation -
Render documentation (depending on hosting / integration, see below) -
Publish documentation (depending on hosting / integration, see below)
Therefore:
-
Where should we host the documentation? I prefer read the docs as they also do the rendering and stuff. There is already a webhook working out of the box: https://read-the-docs.readthedocs.io/en/latest/webhooks.html#gitlab for gitlab. Otherwise we just need a further job in our pipeline triggering the webhook: https://read-the-docs.readthedocs.io/en/latest/webhooks.html#others -
How should we write the docs? I would prefer sphinx: http://www.sphinx-doc.org/en/stable/