Add API docs

.github/workflows/generate_cli_doc.yml

@@ -0,0 +1,67 @@
+name: Update API docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  update_api:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+        working-directory: ./docs-sphinx
+    steps:
+      - name: Check out repository 🛎️
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v1
+        with:
+          python-version: "3.10"
+
+      - name: Install nebari and docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e "../[docs]"
+
+      - name: Generate new API docs
+        run: |
+          make html
+
+      - name: Copy cli doc
+        run: |
+          cp _build/html/cli.html cli.html
+
+      - name: Look for changes to generated docs
+        uses: tj-actions/verify-changed-files@v12
+        id: verify-changed-files
+        with:
+          files: |
+            docs-sphinx/cli.html
+
+      - name: Create Pull Request in code repo
+        id: create_pull_request
+        uses: peter-evans/create-pull-request@v4
+        if: steps.verify-changed-files.outputs.files_changed == 'true'
+        with:
+          token: ${{ secrets.NEBARI_SENSEI_API_DOCS_PR_OPENER }}
+          commit-message: Update api docs
+          committer: GitHub <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch: auto_cli_doc_update
+          delete-branch: true
+          title: '[AUTO] Update CLI doc'
+          body: |
+            Update CLI doc
+            - Auto-generated by [create-pull-request][1]
+
+            [1]: https://github.com/peter-evans/create-pull-request
+          labels: |
+            "area: documentation 📖"
+          draft: false
+          base: ${{ github.head_ref }}

.pre-commit-config.yaml

@@ -25,7 +25,9 @@ repos:
     rev: v4.4.0
     hooks:
       - id: end-of-file-fixer
+        exclude: "^docs-sphinx/cli.html"
       - id: trailing-whitespace
+        exclude: "^docs-sphinx/cli.html"
       - id: check-json
       - id: check-yaml
         # jinja2 templates for helm charts

docs-sphinx/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs-sphinx/README.md

@@ -0,0 +1,30 @@
+# Nebari CLI documentation
+
+The CLI docs are generated using Sphinx and the sphinx-click extension. Although
+a full Sphinx website is required in order to generate the docs, only the
+`cli.html` file is used. This file gets copied over to the nebari-docs repo via
+a GitHub Action.
+
+The rich markup is currently unsupported by `sphinx-click` which means that the
+color additions to the CLI get explicitly written in the docs
+(https://github.com/ewels/rich-click/issues/48).
+
+## Automation via GitHub Actions
+
+_Generating the CLI HTML file_
+
+A GitHub Action will run with every push to either the `dev` or `main` branches
+which generates the documentation. A full Sphinx site build is required. To
+build the site, go to the `docs-sphinx` folder and run
+
+`make html`
+
+The Action will then checks to see if `cli.html` (the generated doc) has
+changed. If it has changed, it will open a new PR with an updated version.
+
+_Updating the Nebari Docs repo_
+
+The Nebari Documentation lives in a separate repo from the code itself
+(https://github.com/nebari-dev/nebari-docs). A separate GitHub Action watches
+for changes to the `cli.html` file in _this_ repo, and keeps it in sync with
+the `cli.html` file in the docs repo.

docs-sphinx/cli.rst

@@ -0,0 +1,6 @@
+Nebari CLI
+==========
+
+.. click:: nebari.__main__:typer_click_app
+   :prog: nebari
+   :nested: full

docs-sphinx/conf.py

@@ -0,0 +1,9 @@
+project = "Nebari CLI documentation"
+copyright = "2023, Nebari"
+author = "Nebari team"
+
+extensions = ["sphinx_click"]
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "alabaster"

docs-sphinx/index.rst

@@ -0,0 +1,21 @@
+.. Nebari API documentation documentation master file, created by
+   sphinx-quickstart on Fri Mar 10 12:28:01 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to Nebari API documentation's documentation!
+====================================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. toctree::
+   cli
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pyproject.toml

@@ -94,6 +94,10 @@ dev = [
     "build",
     "jinja2",
 ]
+docs = [
+    "sphinx",
+    "sphinx_click",
+]
 
 [project.urls]
 Documentation = "https://www.nebari.dev/docs"

src/nebari/__main__.py

@@ -1,3 +1,5 @@
+import typer
+
 from _nebari.cli import create_cli
 
 
@@ -6,5 +8,10 @@ def main():
     cli()
 
 
+# get the click object from the typer app so that we can autodoc the cli
+# NOTE: this must happen _after_ all the subcommands have been added.
+# Adapted from https://typer.tiangolo.com/tutorial/using-click/
+typer_click_app = typer.main.get_command(create_cli())
+
 if __name__ == "__main__":
-    main()
+    typer_click_app()