Make help documentation more concise
- Dominant language
- Python
- Stars
- 855
- Forks
- 92
- PR merge metrics
- No merged PRs in 30d
Description
Current documentation is way too verbose (29 lines, cf [`__doc__`](https://github.com/guyzmo/git-repo/blob/devel/git_repo/repo.py#L3-32)), and it could be written as follows (16 lines!):
```
Usage:
{self} [--path=] [-v...] fork [/] [] [--clone]
{self} [--path=] [-v...] create [/] [--add]
{self} [--path=] [-v...] delete [/] [-f]
{self} [--path=] [-v...] open [/]
{self} [--path=] [-v...] clone / []
{self} [--path=] [-v...] add / [] [--tracking=] [-a]
{self} [--path=] [-v...] request [/] (list|ls)
{self} [--path=] [-v...] request [/] fetch
{self} [--path=] [-v...] request [/] create [ []] [--branch=<remote>] [--message=<message>]
{self} [--path=<path>] [-v...] <target> gist (list|ls) [<gist>]
{self} [--path=<path>] [-v...] <target> gist clone <gist>
{self} [--path=<path>] [-v...] <target> gist fetch <gist> [<gist_file>]
{self} [--path=<path>] [-v...] <target> gist create [--secret] <description> [<gist_path> <gist_path>...]
{self} [--path=<path>] [-v...] <target> gist delete <gist> [-f]
{self} [--path=<path>] [-v...] [<target>] config [--config=<gitconfig>]
{self} --help
```
The issue lies within [_docopt_](https://github.com/docopt/docopt) and I've opened [an issue about it](https://github.com/docopt/docopt/issues/328). Let's hope we'll find a way.
Another approach would be to consider changing the approach of the help page, by going through a refactoring of the current CLI API design, which could be considered for v2.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at git_repo/repo.py lines 3-32 and inspect how docopt builds the CLI help text. Compare the current __doc__ with the proposed 16-line usage block and review the linked docopt issue for constraints. Done means the help documentation is made concise, or the scope is clarified as a v2 CLI refactor.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, python
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100