Automatically generated man pages not integrated in build

[See original issue on GitLab](https://gitlab.com/BuildStream/buildstream/-/issues/8)
In GitLab by [[Gitlab user @tristanvb]](https://gitlab.com/tristanvb) on Apr 13, 2017, 11:56

We use click_man to automatically generate man pages from our usage of click library for the frontend.

However, I was unable to easily integrate the generation of man pages into the build_py step in our setup.py.

The [click-man page](https://github.com/click-contrib/click-man) discourages this, because:
```
If we generate them in our build process and add them to your
distribution we do not have a way to prevent installation to
/usr/share/man for non-UNIX-like Operating Systems.
```

However, frankly we should not care about this. Having the docs included as 'data_files' in the distribution proper, means that they will automatically appear at ${prefix}/share/man/man1, which is perfect because:
* It should be obvious for any distribution that what appears in the python distribution should be installed
* Even if we do support non unix platforms in the future, there is no harm done with having unused man pages installed so long as they are tracked properly by whatever package manager is used.

I have tried to hook this up following the instructions in this [blog post](https://seasonofcode.com/posts/how-to-add-custom-build-steps-and-commands-to-setuppy.html), but have not been able to do so. This should be possible but the documentation is near non existent.

The current workaround is to generate the man pages periodically and commit the result to the buildstream repository, which is far from ideal.

Start in setup.py at the build_py step and review how click-man generation and data_files are configured. Check the click-man documentation and the existing build process first; done means man pages are generated and included in the Python distribution without requiring committed generated files.

Written by the indexing model from the issue text.