Docs fixes

Author: jtpio

docs/source/conf.py

@@ -37,6 +37,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "sphinxarg.ext",
 ]
 
 try:
@@ -48,6 +49,9 @@
 
 myst_enable_extensions = ["html_image", "tasklist"]
 
+# Allow argparse directive in MyST markdown
+myst_fence_as_directive = ["argparse"]
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/source/reference/releaser_cli.md

@@ -2,259 +2,8 @@
 
 The `jupyter-releaser` command-line interface provides tools for managing releases.
 
-## Usage
-
-```bash
-jupyter-releaser [--force] <command> [options]
+```{argparse}
+:module: jupyter_releaser.cli
+:func: create_parser
+:prog: jupyter-releaser
 ```
-
-### Global Options
-
-- `--force`: Force a command to run even when skipped by config
-
-## Commands
-
-### list-envvars
-
-List the environment variables used by the releaser.
-
-### prep-git
-
-Prep git and environment variables.
-
-**Options:**
-
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--username`: The git username (env: `GITHUB_ACTOR`)
-- `--git-url`: A custom url for the git repository
-
-### bump-version
-
-Bump the version.
-
-**Options:**
-
-- `--version-spec`: The new version specifier (env: `RH_VERSION_SPEC`)
-- `--version-cmd`: The version command (env: `RH_VERSION_COMMAND`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--python-packages`: The list of strings of the form "path_to_package:name_of_package" (env: `RH_PYTHON_PACKAGES`)
-- `--tag-format`: The format to use for the release tag (env: `RH_TAG_FORMAT`, default: `v{version}`)
-
-### build-changelog
-
-Build changelog entry.
-
-**Options:**
-
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--since`: Use PRs with activity since this date or git reference (env: `RH_SINCE`)
-- `--since-last-stable`: Use PRs with activity since the last stable git tag (env: `RH_SINCE_LAST_STABLE`)
-- `--resolve-backports`: Resolve backport PRs to their originals (env: `RH_RESOLVE_BACKPORTS`, default: `True`)
-
-### draft-changelog
-
-Create a changelog entry PR.
-
-**Options:**
-
-- `--version-spec`: The new version specifier (env: `RH_VERSION_SPEC`)
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--since`: Use PRs with activity since this date or git reference (env: `RH_SINCE`)
-- `--since-last-stable`: Use PRs with activity since the last stable git tag (env: `RH_SINCE_LAST_STABLE`)
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--post-version-spec`: The post release version (usually dev) (env: `RH_POST_VERSION_SPEC`)
-- `--post-version-message`: The post release message (env: `RH_POST_VERSION_MESSAGE`, default: `Bumped version to {post_version}`)
-- `--silent`: Set a placeholder in the changelog (env: `RH_SILENT`)
-- `--tag-format`: The format to use for the release tag (env: `RH_TAG_FORMAT`, default: `v{version}`)
-
-### extract-changelog
-
-Extract the changelog entry.
-
-**Options:**
-
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-- `--silent`: Set a placeholder in the changelog (env: `RH_SILENT`)
-
-### build-python
-
-Build Python dist files.
-
-**Options:**
-
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--python-packages`: The list of strings of the form "path_to_package:name_of_package" (env: `RH_PYTHON_PACKAGES`)
-
-### check-python
-
-Check Python dist files.
-
-**Options:**
-
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--check-imports`: The Python packages import to check for (env: `RH_CHECK_IMPORTS`)
-- `--pydist-check-cmd`: The command to use to check a python distribution file (env: `RH_PYDIST_CHECK_CMD`)
-- `--pydist-extra-check-cmds`: Extra checks to run against the pydist file (env: `RH_EXTRA_PYDIST_CHECK_CMDS`)
-- `--pydist-resource-paths`: Resource paths that should be available when installed (env: `RH_PYDIST_RESOURCE_PATHS`)
-
-### build-npm
-
-Build npm package.
-
-**Arguments:**
-
-- `package`: The package to build (default: `.`)
-
-**Options:**
-
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-
-### check-npm
-
-Check npm package.
-
-**Options:**
-
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--npm-install-options`: Options to pass when calling npm install (env: `RH_NPM_INSTALL_OPTIONS`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-
-### tag-release
-
-Create release commit and tag.
-
-**Options:**
-
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--tag-format`: The format to use for the release tag (env: `RH_TAG_FORMAT`, default: `v{version}`)
-- `--release-message`: The message to use for the release commit (env: `RH_RELEASE_MESSAGE`, default: `Publish {version}`)
-- `--tag-message`: The message to use for the release tag (env: `RH_TAG_MESSAGE`, default: `Release {tag_name}`)
-- `--no-git-tag-workspace`: Whether to skip tagging npm workspace packages
-
-### populate-release
-
-Populate a release.
-
-**Arguments:**
-
-- `assets`: Asset files to upload
-
-**Options:**
-
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--version-cmd`: The version command (env: `RH_VERSION_COMMAND`)
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-- `--post-version-spec`: The post release version (usually dev) (env: `RH_POST_VERSION_SPEC`)
-- `--post-version-message`: The post release message (env: `RH_POST_VERSION_MESSAGE`)
-- `--silent`: Set a placeholder in the changelog (env: `RH_SILENT`)
-- `--tag-format`: The format to use for the release tag (env: `RH_TAG_FORMAT`, default: `v{version}`)
-
-### delete-release
-
-Delete a draft GitHub release by url to the release page.
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-
-### extract-release
-
-Download and verify assets from a draft GitHub release.
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-
-### publish-assets
-
-Publish release asset(s).
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--dist-dir`: The folder to use for dist files (env: `RH_DIST_DIR`, default: `dist`)
-- `--npm-token`: A token for the npm release (env: `NPM_TOKEN`)
-- `--npm-cmd`: The command to run for npm release (env: `RH_NPM_COMMAND`, default: `npm publish`)
-- `--twine-cmd`: The twine command to run for Python release (env: `TWINE_COMMAND`, default: `pipx run twine upload`)
-- `--npm-registry`: The npm registry to target for publishing (env: `NPM_REGISTRY`, default: `https://registry.npmjs.org/`)
-- `--twine-repository-url`: The pypi registry to target for publishing (env: `TWINE_REPOSITORY_URL`, default: `https://upload.pypi.org/legacy/`)
-- `--npm-tag`: The npm tag (env: `NPM_TAG`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--python-packages`: The list of strings of the form "path_to_package:name_of_package" (env: `RH_PYTHON_PACKAGES`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-
-### publish-release
-
-Publish GitHub release.
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-- `--silent`: Set a placeholder in the changelog (env: `RH_SILENT`)
-
-### ensure-sha
-
-Ensure that a sha has not changed.
-
-**Options:**
-
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--expected-sha`: The expected sha of the branch HEAD (env: `RH_EXPECTED_SHA`)
-
-### forwardport-changelog
-
-Forwardport Changelog Entries to the Default Branch.
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--username`: The git username (env: `GITHUB_ACTOR`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)
-- `--release-url`: A draft GitHub release url (env: `RH_RELEASE_URL`)
-
-### publish-changelog
-
-Remove changelog placeholder entries.
-
-**Options:**
-
-- `--auth`: The GitHub auth token (env: `GITHUB_ACCESS_TOKEN`)
-- `--ref`: The source reference (env: `RH_REF`)
-- `--branch`: The target branch (env: `RH_BRANCH`)
-- `--repo`: The git repo (env: `RH_REPOSITORY`)
-- `--changelog-path`: The path to changelog file (env: `RH_CHANGELOG`, default: `CHANGELOG.md`)
-- `--dry-run`: Run as a dry run (env: `RH_DRY_RUN`)

pyproject.toml

@@ -48,6 +48,7 @@ docs = [
   "sphinx",
   "sphinx-autobuild",
   "sphinx-copybutton",
+  "sphinx-argparse",
   "pip",
   "myst-parser",
   "pydata_sphinx_theme",