revise CLI documentation (#664)

Co-authored-by: Taylor Steinberg <[email protected]>

Author: edavidaja

.github/workflows/main.yml

@@ -120,15 +120,16 @@ jobs:
         fetch-depth: 0
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    - uses: actions/setup-python@v4
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
       with:
-        python-version: 3.8.x
-    - run: pip freeze
-    - run: make docs
+        python-version: 3.12
+    - name: build docs
+      run: make docs
     - uses: actions/upload-artifact@v4
       with:
         name: docs
-        path: docs/site/
+        path: site/
     - uses: aws-actions/configure-aws-credentials@v4
       id: creds
       with:

.github/workflows/preview-docs.yml

@@ -0,0 +1,34 @@
+name: preview docs
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+  workflow_dispatch:
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+            python-version: 3.x
+
+      - name: Install and Build
+        if: github.event.action != 'closed' # You might want to skip the build if the PR has been closed
+        run: |
+          python -m pip install -e ".[docs]"
+          mkdocs build
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./site/

.gitignore

@@ -34,3 +34,4 @@ vetiver-testing/rsconnect_api_keys.json
 
 # license files should not be commited to this repository
 *.lic
+/site/

Makefile

@@ -97,9 +97,25 @@ lint: lint-3.8
 fmt: RUNNER = bash -c
 fmt: fmt-3.8
 
+# Documentation targets
 .PHONY: docs
-docs:
-	$(MAKE) -C docs VERSION=$(VERSION)
+docs: docs-clean docs-build
+
+.PHONY: docs-clean
+docs-clean:
+	rm -rf site
+
+.PHONY: docs-build
+docs-build:
+	uv venv
+	uv pip install ".[docs]"
+	uv run mkdocs build
+
+.PHONY: docs-serve
+docs-serve:
+	uv venv
+	uv pip install -e ".[docs]"
+	uv run mkdocs serve
 
 .PHONY: version
 version:
@@ -137,14 +153,14 @@ sync-latest-to-s3:
 sync-latest-docs-to-s3:
 	aws s3 sync --acl bucket-owner-full-control \
 		--cache-control max-age=0 \
-		docs/site/ \
+		site/ \
 		$(S3_PREFIX)/latest/docs/
 
 .PHONY: promote-docs-in-s3
 promote-docs-in-s3:
 	aws s3 sync --delete --acl bucket-owner-full-control \
 		--cache-control max-age=300 \
-		docs/site/ \
+		site/ \
 		s3://docs.rstudio.com/rsconnect-python/
 
 RSC_API_KEYS=vetiver-testing/rsconnect_api_keys.json