[README-7] Add documentation for cli (#56)

* docs: add ghlabel.md * docs: document commands dump and setup * docs: describe setup options * chore: add whitespace * test: emoji * test: more emoji * docs: add .env override and removing more labels example * docs: add example for adding more labels * feat: strict is unsafe, default to no-strict * docs: insert ghlabel.md to README.md
seyLu · Sep 8, 2023 · 9ec3d08 · 9ec3d08
1 parent cef3a38
commit 9ec3d08
Show file tree

Hide file tree

Showing 4 changed files with 261 additions and 11 deletions.
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ python==3.11
 
 <br>
 
-### Usage
+### Setup
 
 #### 1. Clone the repo
 
@@ -67,10 +67,126 @@ GITHUB_REPO_OWNER=<target_github_repository_owner>
 GITHUB_REPO_NAME=<target_github_repository_name>
 ```
 
-#### 4. Run the CLI tool
+<br>
+
+## :red_circle: `ghlabel`
+
+Setup Github Labels from a yaml/json config file.
+
+### Usage:
+
+```console
+$ ghlabel [OPTIONS] COMMAND [ARGS]...
+```
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--version`, `-v`
+Show version and exit.
+#### `--debug`, `-D`
+Enable debug mode and show logs.
+#### `--help`
+Show this message and exit.
+
+<br>
+
+### Commands:
+
+#### `dump`
+Generate starter labels config files.
+#### `setup`
+Add/Remove Github labels from config files.
+
+<br>
+
+## :red_circle: `ghlabel dump`
+
+Generate starter labels config files.
+
+### Usage:
+
+```console
+$ ghlabel dump [OPTIONS]
+```
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--new`, `-n` / `--keep-old-labels`, `-N` [default: new]
+Deletes all files in labels dir.
+#### `--dir`, `-d TEXT` [default: labels]
+Specify the dir where to find labels.
+#### `--ext`, `-e [json|yaml]` [default: yaml]
+Label file extension.
+#### `--app`, `-a [app|game|web]` [default: app]
+App to determine label template.
+#### `--help`
+Show this message and exit.
+
+<br>
+
+## :red_circle: `ghlabel setup`
+
+Add/Remove Github labels from config files.
+
+### Usage:
+
+```console
+$ ghlabel setup [TOKEN] [REPO_OWNER] [REPO_NAME] [OPTIONS]
+```
+
+<br>
+
+### :large_blue_diamond: Arguments:
+
+#### `TOKEN` [optional]
+#### `REPO_OWNER` [optional]
+#### `REPO_NAME` [optional]
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--dir`, `-d TEXT` [default: labels]
+Specify the dir where to find labels.
+#### `--strict`, `-s` / `--no-strict`, `-S` [default: no-strict]
+Strictly mirror Github labels from labels config.
+#### `--add-labels`, `-a TEXT`
+Add more labels.
+#### `--remove-labels`, `-r TEXT`
+Remove more labels.
+#### `--remove-all`, `-R [disable|enable|silent]`  [default: disable]
+Remove all Github labels.
+#### `--help`
+Show this message and exit.
 
-```py
-python scripts/setup_github_label.py
+<br>
+
+### Example Usage
+
+#### Overriding `.env` or Manually adding Environment Variables
+
+```bash
+REPO_NAME=medrec ghlabel setup
+```
+
+#### Removing more labels
+
+```bash
+# -r [comma-separated string]
+# will be parsed as list[str]
+ghlabel setup -r "Type: Feature Request, Type: Bug"
+```
+
+#### Adding more labels
+
+```bash
+# -a [valid json string]
+# will be parsed as list[dict[str, str]]
+ghlabel setup -a "[{'name': 'wontfix', 'color': '##ffffff'}, {'name': 'bug', 'color': '#d73a4a', 'description': 'Something isn't working'}]"
 ```
 
 <br>

diff --git a/cli.py b/cli.py
@@ -60,10 +60,10 @@ class RemoveAllChoices(str, Enum):
     silent = "silent"
 
 
-app = typer.Typer()
+app = typer.Typer(add_completion=False)
 
 
-@app.command("setup")  # type: ignore[misc]
+@app.command("setup", help="Add/Remove Github labels from config files.")  # type: ignore[misc]
 def setup_labels(
     token: Annotated[
         Optional[str],
@@ -101,7 +101,7 @@ def setup_labels(
             "-s/-S",
             help="Strictly mirror Github labels from labels config.",
         ),
-    ] = True,
+    ] = False,
     add_labels: Annotated[
         Optional[str],
         typer.Option(
@@ -167,7 +167,7 @@ def setup_labels(
         github_label.add_labels(labels=parse_add_labels(add_labels))
 
 
-@app.command("dump")  # type: ignore[misc]
+@app.command("dump", help="Generate starter labels config files.")  # type: ignore[misc]
 def app_dump(
     new: Annotated[
         bool,
@@ -224,16 +224,20 @@ def app_callback(
             "-v",
             callback=version_callback,
             is_eager=True,
+            help="Show version and exit.",
         ),
     ] = False,
     debug: Annotated[
         bool,
         typer.Option(
             "--debug",
             "-D",
+            help="Enable debug mode and show logs.",
         ),
     ] = False,
 ) -> None:
+    """Setup Github Labels from a yaml/json config file."""
+
     if not debug:
         logger = logging.getLogger("root")
         logger.setLevel(logging.ERROR)

diff --git a/ghlabel.md b/ghlabel.md
@@ -0,0 +1,121 @@
+
+
+## :red_circle: `ghlabel`
+
+Setup Github Labels from a yaml/json config file.
+
+### Usage:
+
+```console
+$ ghlabel [OPTIONS] COMMAND [ARGS]...
+```
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--version`, `-v`
+Show version and exit.
+#### `--debug`, `-D`
+Enable debug mode and show logs.
+#### `--help`
+Show this message and exit.
+
+<br>
+
+### Commands:
+
+#### `dump`
+Generate starter labels config files.
+#### `setup`
+Add/Remove Github labels from config files.
+
+<br>
+
+## :red_circle: `ghlabel dump`
+
+Generate starter labels config files.
+
+### Usage:
+
+```console
+$ ghlabel dump [OPTIONS]
+```
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--new`, `-n` / `--keep-old-labels`, `-N` [default: new]
+Deletes all files in labels dir.
+#### `--dir`, `-d TEXT` [default: labels]
+Specify the dir where to find labels.
+#### `--ext`, `-e [json|yaml]` [default: yaml]
+Label file extension.
+#### `--app`, `-a [app|game|web]` [default: app]
+App to determine label template.
+#### `--help`
+Show this message and exit.
+
+<br>
+
+## :red_circle: `ghlabel setup`
+
+Add/Remove Github labels from config files.
+
+### Usage:
+
+```console
+$ ghlabel setup [TOKEN] [REPO_OWNER] [REPO_NAME] [OPTIONS]
+```
+
+<br>
+
+### :large_blue_diamond: Arguments:
+
+#### `TOKEN` [optional]
+#### `REPO_OWNER` [optional]
+#### `REPO_NAME` [optional]
+
+<br>
+
+### :large_orange_diamond: Options:
+
+#### `--dir`, `-d TEXT` [default: labels]
+Specify the dir where to find labels.
+#### `--strict`, `-s` / `--no-strict`, `-S` [default: no-strict]
+Strictly mirror Github labels from labels config.
+#### `--add-labels`, `-a TEXT`
+Add more labels.
+#### `--remove-labels`, `-r TEXT`
+Remove more labels.
+#### `--remove-all`, `-R [disable|enable|silent]`  [default: disable]
+Remove all Github labels.
+#### `--help`
+Show this message and exit.
+
+<br>
+
+### Example Usage
+
+#### Overriding `.env` or Manually adding Environment Variables
+
+```bash
+REPO_NAME=medrec ghlabel setup
+```
+
+#### Removing more labels
+
+```bash
+# -r [comma-separated string]
+# will be parsed as list[str]
+ghlabel setup -r "Type: Feature Request, Type: Bug"
+```
+
+#### Adding more labels
+
+```bash
+# -a [valid json string]
+# will be parsed as list[dict[str, str]]
+ghlabel setup -a "[{'name': 'wontfix', 'color': '##ffffff'}, {'name': 'bug', 'color': '#d73a4a', 'description': 'Something isn't working'}]"
+```
diff --git a/scripts/setup_github_label.py b/scripts/setup_github_label.py
@@ -165,8 +165,15 @@ def _fetch_github_labels(self, github_config: GithubConfig) -> list[dict[str, st
     def _load_labels_from_config(self) -> list[dict[str, str]]:
         use_labels: list[dict[str, str]] = []
         labels: list[dict[str, str]] = []
+        files_in_dir: list[str] = []
 
-        files_in_dir: list[str] = os.listdir(self.dir)
+        try:
+            files_in_dir = os.listdir(self.dir)
+        except FileNotFoundError:
+            logging.error(
+                f"No {self.dir} dir found. To solve this issue, first run `ghlabel dump`."
+            )
+            sys.exit()
 
         yaml_filenames: list[str] = list(
             filter(
@@ -194,7 +201,9 @@ def _load_labels_from_config(self) -> list[dict[str, str]]:
             label_filenames.extend(json_filenames)
             label_ext = "json"
         else:
-            logging.error("No Yaml or JSON config file for labels.")
+            logging.error(
+                "No Yaml or JSON config file found for labels. To solve this issue, first run `ghlabel dump`."
+            )
             sys.exit()
 
         for label_filename in label_filenames:
@@ -370,7 +379,7 @@ def add_labels(self, labels: list[dict[str, str]] | None = None) -> None:
 
 def main() -> None:
     github_label = GithubLabel()
-    github_label.remove_labels(strict=True)
+    github_label.remove_labels()
     github_label.add_labels()