Automatically keep usage text in sync

[aspiers]

I'm not sure it's a good idea to copy'n'paste the usage text into the README because violation of the DRY rule makes it uncomfortably easy to forget to update it whenever the usage text is changed via changes in the code, and then they get out of sync. But if you are convinced neither you nor any future maintainer will ever forget then I guess you can ignore me and close this ;-)

[kdeldycke]

Agree with this one: it's a pain to keep the usage output in sync.

The reason I included this right away in the README is to allow potential users to get an idea of the capabilities without installing the package.

I'll maintain it's still a good trade-off. But I'll welcome any hints on how we could automate this.

[kdeldycke]

CLI usage has moved to its own dedicated page in the documentation: https://maildir-deduplicate.readthedocs.io/en/develop/usage.html

We now need to find a way to keep in sync the CLI help messages with the current implementation.

[leggewie]

Well, the build tools need to run mdedup --help > docs/usage.rst after a successful build and docs/usage.rst needs to be added to .gitignore. Can poetry do this?

[kdeldycke]

This automation can be part of the documentation step in the autofix.yaml workflow:

mail-deduplicate/.github/workflows/autofix.yaml

Lines 68 to 95 in 59ff12d

	documentation:
	name: Generate Sphinx doc and create a PR
	runs-on: ubuntu-20.04
	steps:
	- uses: actions/[email protected]
	- uses: actions/[email protected]
	- name: Install Sphinx
	run: |
	python -m pip install --upgrade pip
	python -m pip install --upgrade poetry
	poetry install --extras docs
	- name: Run Sphinx
	run: |
	poetry run sphinx-apidoc -f -o ./docs .
	- uses: peter-evans/[email protected]
	with:
	author: "Kevin Deldycke <[email protected]>"
	commit-message: "[autofix] Update Sphinx apidoc"
	title: "[autofix] Update Sphinx apidoc"
	body: >
	[Auto-generated on run
	#${{ github.run_id }}](https://github.com/${{ github.repository
	}}/actions/runs/${{ github.run_id }}) as defined by [workflow
	action](https://github.com/${{ github.repository
	}}/blob/${{ github.base_ref }}/.github/workflows/autofix.yaml).
	labels: CI/CD, documentation
	assignees: kdeldycke
	branch: update-doc

[kdeldycke]

The old usage page in the documentation (https://maildir-deduplicate.readthedocs.io/en/develop/usage.html) has been moved to https://kdeldycke.github.io/mail-deduplicate/cli-parameters.html , which now relies on the .. click:: directive from sphinx-click to keep the help text of the CLI in sync.

Still missing:

• The strategy list at the bottom of the help screen that is dynamically generated
• The various screenshots, that we can generate with tools like vhs