#70 Maintaining project's manpages and docs.
Opened 3 years ago by lruzicka. Modified 3 years ago

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.


My opinion is that now virt-install supports the --cloud-init option, there is not much motivation to invest a lot of energy into testcloud. I would even say it's not a smart way of using our time. I'm very pragmatic in this and feel no nostalgia for a project I spent decent time contributing to. It's better to have the functionality maintained by someone else in a big upstream project. That's the dream coming true, isn't it?

However, in other tickets it has been clear that not everybody agrees with me (even though I'm not completely clear on their reasoning). So those people might want to get involved in this, but I'll mostly stay out of it. Don't expect feedback from me, sorry. Things would change if virt-install's implementation proved to be problematic, but so far I've been quite happy with the experience (with the exception of one bug which was promptly fixed in a few days and will be gone in the next release).

Login to comment on this ticket.

Metadata