Add API docs

.github/workflows/update_api_docs.yml

@@ -0,0 +1,82 @@
+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/api_docs
+    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: |
+          echo "generate the new docs"
+          pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md
+          echo "make modifications to clean up"
+          python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md
+
+      - name: Lint the new docs
+        continue-on-error: true
+        run: |
+          echo "run linting and formatting"
+          pre-commit run --files api_doc.md
+          echo "run it again to prove its clean now"
+          pre-commit run --files api_doc.md
+
+      - name: Check for changes
+        run: |
+          if git diff --exit-code; then
+            echo "changes_exist=true" >> $GITHUB_ENV
+          else
+            echo "changes_exist=false" >> $GITHUB_ENV
+          fi
+
+      - name: Look for changes to cli files
+        uses: tj-actions/verify-changed-files@v12
+        id: verify-changed-files
+        with:
+          files: |
+            docs/api_docs/api_doc.md
+
+      - 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 report
+          committer: GitHub <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch: auto_api_doc_update
+          delete-branch: true
+          title: '[AUTO] Update API doc'
+          body: |
+            Update API 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 }}

.gitignore

@@ -1,6 +1,7 @@
 # docs
 .nox
 _build
+docs/api_docs/api_temp.md
 
 # setuptools scm
 nebari/_version.py

docs/.gitignore

@@ -70,3 +70,6 @@ yarn-error.log*
 
 app/__pycache__
 docs/users.pdf
+
+# docs
+docs/api_docs/api_temp.md

docs/api_docs/README.md

@@ -0,0 +1,28 @@
+# Nebari API docs
+
+The Nebari API docs are generated from this repo, then merged into the nebari-docs repo via PR opened by GitHub Actions.
+
+## Environment
+
+From the root of the repo:
+
+```bash
+pip install -e ".[docs]"
+```
+
+## Workflow
+
+The docs may be built manually through the following workflow, or executed as part of an autoupdate via GH Actions CI.
+
+The workflow described below will create the API docs and run a formatting script to do a bit of cleanup.
+
+```bash
+# work out of the api_docs directory in the nebari repo
+cd docs/api_docs/
+# auto generate the api docs
+pydoc-markdown -I "../../" -p nebari --render-toc > api_temp.md
+# make formatting modifications and copy into the docs repo
+python api_doc_mods.py --autogen_path api_temp.md --outpath api_doc.md
+# run linting and formatting
+pre-commit run --files api_doc.md
+```