Hello everybody (especially @kparal, @lbrabec, @frantisekz, @jskladan, @tflink),

František asked me to update the source data for man pages of this project, because he might have liked how README.md was updated. I decided to take a look around and learn about how to create man pages.

I realized the following situation:

1. Currently, the README.md is the most up-to-date description of the project. I have loaded the content of the file to Gdoc for discussion about the content, see https://docs.google.com/document/d/1-tGFy0Nn-fMqYGY4wJRRUtLiq1JHKBxX_8QeW9SSHHs/edit?usp=sharing and feel free to comment or request changes.
2. There is an incomplete reST documentation in the docs directory that could be automatically generated with Sphinx.
3. No man pages are installed by the stable versions so far.
4. František updated the specs so that man pages are generated from the reST documentation (this also includes the API guide - automatically generated from the source code when Sphinx runs).

I believe, that the current status quo is not optimal and could be enhanced. Therefore, I am suggesting following changes and updates.

1. Provide a standalone man page content that does not need Sphinx generation, where only relevant pieces of info about the usage of the testcloud command would live. Using the docs directory to create man pages results in a man page with redundant info (about API calls, for instance) that are useless when people want to use the testcloud command on the CLI. You can see a draft here (written in troff): https://pagure.io/fork/lruzicka/testcloud/blob/feature/manpages/f/manpages/testcloud.1. You can see the formatted output when you download the file and open it using man -l testcloud.1.
2. Polish the content of the README.md file and use it to create a proper documentation in the docs directory, written in reST, so that API guide can be generated automatically as is the current situation.
3. Shorten the README.md to only provide basic info about the project and not the documentation itself.

I am willing to work on this. Please let me know, what you think. Thanks.