Document CLI

Author: robbievanleeuwen

README.md

@@ -14,9 +14,11 @@ uv tool install upgrade-dependencies
 You can then navigate to your project directory and execute:
 
 ```
-uvx upgrade-dependencies [OPTIONS] [COMMAND]
+uvx upgrade-dependencies [OPTIONS] COMMAND [ARGS]...
 ```
 
+See the [CLI documentation](docs/usage.md) for information about how each command works.
+
 ### Requirements
 
 All python requirements are installed by default. To successfully use the `update`

docs/usage.md

@@ -0,0 +1,133 @@
+# `upgrade-dependencies`
+
+**Usage**:
+
+```console
+$ upgrade-dependencies [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `list-dependencies`: List all the dependencies for the project.
+* `check-dependency`: Checks whether a dependency needs updating.
+* `needs-updating`: Lists the dependencies that need updating.
+* `latest-versions`: List the dependencies that aren't specified to the latest version.
+* `update`: Updates a dependency to a specific (or latest) version.
+* `format-yml`: Formats the workflow and pre-commit config yaml files.
+
+## `upgrade-dependencies list-dependencies`
+
+List all the dependencies for the project.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies list-dependencies [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `upgrade-dependencies check-dependency`
+
+Checks whether a dependency needs updating.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies check-dependency [OPTIONS] DEPENDENCY
+```
+
+**Arguments**:
+
+* `DEPENDENCY`: Name of the dependency to check  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `upgrade-dependencies needs-updating`
+
+Lists the dependencies that need updating.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies needs-updating [OPTIONS]
+```
+
+**Options**:
+
+* `--base / --no-base`: Include base dependencies  [default: base]
+* `--optional-deps / --no-optional-deps`: Include optional dependencies  [default: optional-deps]
+* `--group-deps / --no-group-deps`: Include dependency groups  [default: group-deps]
+* `--github-actions / --no-github-actions`: Include GitHub actions dependencies  [default: github-actions]
+* `--pre-commit / --no-pre-commit`: Include pre-commit dependencies  [default: pre-commit]
+* `--help`: Show this message and exit.
+
+## `upgrade-dependencies latest-versions`
+
+List the dependencies that aren't specified to the latest version.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies latest-versions [OPTIONS]
+```
+
+**Options**:
+
+* `--base / --no-base`: Include base dependencies  [default: base]
+* `--optional-deps / --no-optional-deps`: Include optional dependencies  [default: optional-deps]
+* `--group-deps / --no-group-deps`: Include dependency groups  [default: group-deps]
+* `--github-actions / --no-github-actions`: Include GitHub actions dependencies  [default: no-github-actions]
+* `--pre-commit / --no-pre-commit`: Include pre-commit dependencies  [default: pre-commit]
+* `--help`: Show this message and exit.
+
+## `upgrade-dependencies update`
+
+Updates a dependency to a specific (or latest) version.
+
+Makes changes to the dependency specification locally and creates a GitHub pull
+request on a new branch (branch name = dependency/{package_name}-{version}). Make
+sure this branch name does not exist locally or on GitHub.
+
+Requires git and the GitHub CLI to be installed. It is recommended to have a clean
+git before running this command.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies update [OPTIONS] DEPENDENCY
+```
+
+**Arguments**:
+
+* `DEPENDENCY`: Dependency to update  [required]
+
+**Options**:
+
+* `--version TEXT`: Version to update to, latest version if not specified
+* `--target-branch TEXT`: Name of the branch to merge PR to  [default: master]
+* `--help`: Show this message and exit.
+
+## `upgrade-dependencies format-yml`
+
+Formats the workflow and pre-commit config yaml files.
+
+**Usage**:
+
+```console
+$ upgrade-dependencies format-yml [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.

src/upgrade_dependencies/main.py

@@ -2,7 +2,7 @@
 
 import asyncio
 import os
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Annotated
 
 import typer
 from packaging.version import Version
@@ -25,7 +25,7 @@
 
 @app.command()
 def list_dependencies():
-    """Checks whether a dependency needs updating."""
+    """List all the dependencies for the project."""
     project = Project(gh_pat=GH_PAT)
 
     # base dependencies
@@ -119,12 +119,10 @@ def list_dependencies():
 
 
 @app.command()
-def check_dependency(dependency: str):
-    """Checks whether a dependency needs updating.
-
-    Args:
-        dependency: Name of the dependency to check.
-    """
+def check_dependency(
+    dependency: Annotated[str, typer.Argument(help="Name of the dependency to check")],
+):
+    """Checks whether a dependency needs updating."""
     project = Project(gh_pat=GH_PAT)
 
     try:
@@ -156,24 +154,22 @@ def check_dependency(dependency: str):
 
 @app.command()
 def needs_updating(
-    base: bool = True,
-    optional_deps: bool = True,
-    group_deps: bool = True,
-    github_actions: bool = True,
-    pre_commit: bool = True,
+    base: Annotated[bool, typer.Option(help="Include base dependencies")] = True,
+    optional_deps: Annotated[
+        bool,
+        typer.Option(help="Include optional dependencies"),
+    ] = True,
+    group_deps: Annotated[bool, typer.Option(help="Include dependency groups")] = True,
+    github_actions: Annotated[
+        bool,
+        typer.Option(help="Include GitHub actions dependencies"),
+    ] = True,
+    pre_commit: Annotated[
+        bool,
+        typer.Option(help="Include pre-commit dependencies"),
+    ] = True,
 ):
-    """List the dependencies that need updating.
-
-    Args:
-        base: If set to True, includes the base dependencies. Defaults to True.
-        optional_deps: If set to True, includes the optional dependencies. Defaults to
-            True.
-        group_deps: If set to True, includes the dependency groups. Defaults to True.
-        github_actions: If set to True, includes the github actions dependencies.
-            Defaults to True.
-        pre_commit: If set to True, includes the pre-commit dependencies. Defaults to
-            True.
-    """
+    """Lists the dependencies that need updating."""
     # create project object
     project = Project(gh_pat=GH_PAT)
 
@@ -225,24 +221,22 @@ def needs_updating(
 
 @app.command()
 def latest_versions(
-    base: bool = True,
-    optional_deps: bool = True,
-    group_deps: bool = True,
-    github_actions: bool = False,
-    pre_commit: bool = True,
+    base: Annotated[bool, typer.Option(help="Include base dependencies")] = True,
+    optional_deps: Annotated[
+        bool,
+        typer.Option(help="Include optional dependencies"),
+    ] = True,
+    group_deps: Annotated[bool, typer.Option(help="Include dependency groups")] = True,
+    github_actions: Annotated[
+        bool,
+        typer.Option(help="Include GitHub actions dependencies"),
+    ] = False,
+    pre_commit: Annotated[
+        bool,
+        typer.Option(help="Include pre-commit dependencies"),
+    ] = True,
 ):
-    """List the dependencies that aren't pinned to the latest version.
-
-    Args:
-        base: If set to True, includes the base dependencies. Defaults to True.
-        optional_deps: If set to True, includes the optional dependencies. Defaults to
-            True.
-        group_deps: If set to True, includes the dependency groups. Defaults to True.
-        github_actions: If set to True, includes the github actions dependencies.
-            Defaults to False.
-        pre_commit: If set to True, includes the pre-commit dependencies. Defaults to
-            True.
-    """
+    """List the dependencies that aren't specified to the latest version."""
     # create project object
     project = Project(gh_pat=GH_PAT)
 
@@ -294,18 +288,24 @@ def latest_versions(
 
 @app.command()
 def update(
-    dependency: str,
-    version: str | None = None,
-    target_branch: str = "master",
+    dependency: Annotated[str, typer.Argument(help="Dependency to update")],
+    version: Annotated[
+        str | None,
+        typer.Option(help="Version to update to, latest version if not specified"),
+    ] = None,
+    target_branch: Annotated[
+        str,
+        typer.Option(help="Name of the branch to merge PR to"),
+    ] = "master",
 ):
-    """_summary_.
+    """Updates a dependency to a specific (or latest) version.
 
-    Make sure branch locally and on github do not already exist!
+    Makes changes to the dependency specification locally and creates a GitHub pull
+    request on a new branch (branch name = dependency/{package_name}-{version}). Make
+    sure this branch name does not exist locally or on GitHub.
 
-    Args:
-        dependency: _description_
-        version: _description_
-        target_branch: _description_
+    Requires git and the GitHub CLI to be installed. It is recommended to have a clean
+    git before running this command.
     """
     with Progress(
         SpinnerColumn(),

todo.md

@@ -11,7 +11,8 @@
 - [x] Create changes to files
 - [x] Create pull request
 - [x] Add format yml files
-- [ ] Documentation
+- [x] Documentation
+- [ ] Add release command
 - [ ] Handle uv better (not group)
 - [ ] Handle pre-commit yml extension (not yaml)
 - [ ] Add tests