Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Automatically keep usage text in sync #23

Open
aspiers opened this issue Apr 1, 2015 · 5 comments
Open

Automatically keep usage text in sync #23

aspiers opened this issue Apr 1, 2015 · 5 comments
Assignees
Labels
🤖 ci Continuous integration, tests, automation and management of the project 📚 documentation Update to non-code (readme, docstrings, typos, …)

Comments

@aspiers
Copy link
Contributor

aspiers commented Apr 1, 2015

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
Copy link
Owner

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 kdeldycke added this to the 1.0.0 milestone Sep 18, 2015
@kdeldycke kdeldycke self-assigned this Sep 18, 2015
@kdeldycke kdeldycke changed the title usage text in README violates DRY Usage text in README violates DRY Sep 18, 2015
@kdeldycke kdeldycke removed this from the 1.0.0 milestone Oct 3, 2015
@kdeldycke kdeldycke changed the title Usage text in README violates DRY Automatically keep usage text in sync Nov 13, 2016
@kdeldycke
Copy link
Owner

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
Copy link
Contributor

leggewie commented May 20, 2021

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
Copy link
Owner

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

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 kdeldycke added 📚 documentation Update to non-code (readme, docstrings, typos, …) 🙏 help wanted I can't do this alone and need contributors 🤖 ci Continuous integration, tests, automation and management of the project and removed documentation labels Nov 23, 2022
@kdeldycke
Copy link
Owner

kdeldycke commented Nov 26, 2022

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:

@kdeldycke kdeldycke removed the 🙏 help wanted I can't do this alone and need contributors label Dec 9, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🤖 ci Continuous integration, tests, automation and management of the project 📚 documentation Update to non-code (readme, docstrings, typos, …)
Projects
None yet
Development

No branches or pull requests

3 participants