I agree, it would be better to be able to automatically put the output of help in the README.

I agree with using pre-commit-hooks. Therefore, I will try to set up pre-commit-hooks.

What about including only the usage lines in README? Full help output would make a long README even longer + description on PyPI.

(If you do decide to go for full help output, then cog may help)

Another option for generating the full output is using wheezy.template:

1. Move the current readme to a template file, like README.rst.wz, maybe in a new templates folder
2. Add a section like this to the template:

Usage
=====

``pip-compile``
---------------

::
@(
    from subprocess import run
    from textwrap import indent
    pip_compile_usage = run(['pip-compile', '--help'], capture_output=True).stdout.decode()
    pip_compile_usage = indent(pip_compile_usage, '   ')
)
@pip_compile_usage

``pip-sync``
------------

::
@(
    from subprocess import run
    from textwrap import indent
    pip_sync_usage = run(['pip-sync', '--help'], capture_output=True).stdout.decode()
    pip_sync_usage = indent(pip_sync_usage, '   ')
)
@pip_sync_usage

3. From an environment with wheezy.template and the local pip-tools installed, run wheezy.template templates/README.rst.wz '{}' >README.rst

I am going to close this for the stated reasons. I am not against including output of --help into docs but not on readme, unless the implementation (lint?) will update the readme automatically. I do not want anyone to have to remember that this output needs to updated on each merge.