Add usage help of command line tool to README.rst

I wrote a little command line tool, and want to add the "--help" usage message to the docs.

Since I am lazy, I would like to make the update procedure as simple as possible. Here is what I want to the update workflow to look like:

Update code which results in an updates usage message.
Run a script which updates the docs: The new usage message should be visible in the docs.

In other word: I don't want to copy+paste the usage message.

Step1 is comes from my own brain. But want to reuse existing tools for Step2.

Up to now the docs are just a simple README.rst file.

I would like to stick with a simple solution, where the docs can be visible directly via github. Up to now, I don't need the more complicated solution (like readthedocs).

How can I avoid copy+pasting the --help usage message?

Here is the tool I am working on: https://github.com/guettli/reprec

Solution

As suggested in the comments, you could use a git pre-commit hook to generate the README.rst file on commit. You could use an existing tool such as cog, or you could just do something very simple with bash.

For example, create a RST "template" file:

README.rst.tmpl

Test Git pre-commit hook project
--------------------------------

>>> INSERTION POINT FOR HELP OUTPUT <<<

.git/hooks/pre-commit

# Sensible to set -e to ensure we exit if anything fails
set -e

# Get the output from your tool.
# Paths are relative to the root of the repo
output=$(tools/my-cmd-line-tool --help)

cat README.rst.tmpl |
while read line
do
  if [[ $line == ">>> INSERTION POINT FOR HELP OUTPUT <<<" ]]
  then
    echo "$output"
  else
    echo "$line"
  fi
done > README.rst
git add README.rst

This gets run before you are prompted for a commit message, if you didn't pass one on the command line. So when the commit takes place if there were any changes to either README.rst.tmpl or the output from your tool, README.rst will be updated with it.

Edit

I believe this should work on Windows too, or something very similar, since git comes with a bash implementation on Windows, but I haven't tested it.