guyzmo / guyzmo/git-repo

Make help documentation more concise

Open
#27 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.