Merge branch 'posit-dev:main' into main

.github/workflows/ci.yaml

@@ -0,0 +1,66 @@
+name: CI
+on:
+  - push
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          check-latest: true
+          cache: 'pip'
+      - run: make deps
+      - run: make lint
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - '3.8'
+          - '3.9'
+          - '3.10'
+          - '3.11'
+          - '3.12'
+    steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        check-latest: true
+        cache: 'pip'
+    - run: make deps
+    - run: make dev
+    - run: make test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          check-latest: true
+          cache: 'pip'
+      - run: make deps
+      - run: make build
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          check-latest: true
+          cache: 'pip'
+      - uses: quarto-dev/quarto-actions/setup@v2
+      - run: make deps
+      - run: make dev
+      - run: make docs

.github/workflows/coverage-report.yaml

@@ -0,0 +1,26 @@
+name: Coverage Report
+on:
+  workflow_run:
+    workflows: ["Coverage"]
+    types:
+      - completed
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write
+jobs:
+  default:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: coverage.xml
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: orgoro/[email protected]
+        with:
+            coverageFile: coverage.xml
+            token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/coverage.yaml

@@ -0,0 +1,25 @@
+name: Coverage
+on:
+  - pull_request
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  cov:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          check-latest: true
+          cache: 'pip'
+      - run: make deps
+      - run: make dev
+      - run: make test
+      - run: make cov-xml
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage.xml
+          path: coverage.xml
+          retention-days: 1

.vscode/settings.json

@@ -7,4 +7,4 @@
     "cSpell.words": [
         "mypy"
     ]
-}
+}

CONTRIBUTING.md

@@ -10,42 +10,57 @@ Before contributing to the `posit-sdk`, ensure that the following prerequisites
 
 - Python >=3.8
 
+> [!TIP]
+> We recommend using virtual environments to maintain a clean and consistent development environment.
+
 ## Instructions
 
+> [!WARNING]
+> Executing `make` will utilize `pip` to install third-party packages in your activated Python environment. Please review the [`Makefile`](./Makefile) to verify behavior before executing any commands.
+
 1. Fork the repository and clone it to your local machine.
 1. Create a new branch for your feature or bug fix.
 1. Run `make` to run the default development workflow.
 1. Make your changes and test them thoroughly using `make test`
+1. Run `make fmt`, `make lint`, and `make fix` to verify adherence to the project style guide.
 1. Commit your changes and push them to your forked repository.
 1. Submit a pull request to the main repository.
 
-Please ensure that your code follows the project's coding conventions and style guidelines using the configured pre-commit hooks. Run `pre-commit install` install to configure this functionality on your machine.
-
-Also, make sure to include tests for any new functionality or bug fixes.
-
 ## Tooling
 
 Use the default make target to execute the full build pipeline. For details on specific targets, refer to the [Makefile](./Makefile).
 
+## Style Guide
+
+We use [Ruff](https://docs.astral.sh/ruff/) for linting and code formatting. All proposed changes must successfully pass the `make lint` rules prior to merging.
+
+Utilize `make fmt lint fix` to format and lint your changes.
+
+### (Optional) pre-commit
+
+This project is configured for [pre-commit](https://pre-commit.com). Once enabled, a `git commit` hook is created, which invokes `make fmt lint fix`.
+
+To enable pre-commit on your machine, run `pre-commit install`.
+
 ## Release
 
 ### Instructions
 
 To start a release create a semver compatible tag.
 
-_For this example, we will use the tag `v0.0.dev0`. This tag already exists, so you will not be able run the following commands verbatim._
+_For this example, we will use the tag `v0.1.0`. This tag already exists, so you will not be able run the following commands verbatim._
 
 **Step 1**
 
 Create a proper SemVer compatible tag. Consult the [SemVer specification](https://semver.org/spec/v2.0.0.html) if you are unsure what this means.
 
-`git tag v0.0.dev0`
+`git tag v0.1.0`
 
 **Step 2**
 
 Push the tag GitHub.
 
-`git push origin v0.0.dev0`
+`git push origin v0.1.0`
 
 This command will trigger the [Release GitHub Action](https://github.com/posit-dev/posit-sdk-py/actions/workflows/release.yaml).
 
@@ -55,4 +70,4 @@ Once complete, the release will be available on [PyPI](https://pypi.org/project/
 
 ### Pre-Releases
 
-Any tags denoted as a pre-release as defined by the [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) specification will be marked as such in GitHub. For example, the `v0.0.dev0` is a pre-release. Tag `v0.0.0` is a standard-release. Please consult the specification for additional information.
+Any tags denoted as a pre-release as defined by the [SemVer 2.0.0](https://semver.org/spec/v2.0.0.html) specification will be marked as such in GitHub. For example, the `v0.1.rc1` is a pre-release. Tag `v0.1.0` is a standard-release. Please consult the specification for additional information.

Makefile

@@ -4,23 +4,16 @@
 NAME := posit-sdk
 
 # Command aliases
-PIP := pip3
 PYTHON := python3
 
-.PHONY:
-	build
-	clean
-	cov
-	default
-	deps
-	dev
-	fmt
-	fix
-	install
-	lint
-	test
-	uninstall
-	version
+# Check if 'uv' is available
+ifneq ($(shell command -v uv 2>/dev/null),)
+PIP := uv pip
+else
+PIP := pip3
+endif
+
+.PHONY: build clean cov default deps dev docs fmt fix install lint test uninstall version
 
 # Default target that runs the necessary steps to build the project
 all: deps dev test lint build
@@ -31,11 +24,12 @@ build:
 
 # Target for cleaning up generated files and directories
 clean:
+	rm -rf .coverage .mypy_cache .pytest_cache .ruff_cache *.egg-info build coverage.xml dist htmlcov coverage.xml
 	find . -name "*.egg-info" -exec rm -rf {} +
 	find . -name "*.pyc" -exec rm -f {} +
 	find . -name "__pycache__" -exec rm -rf {} +
 	find . -name "_version.py" -exec rm -rf {} +
-	rm -rf .coverage .mypy_cache .pytest_cache .ruff_cache *.egg-info build coverage.xml dist htmlcov coverage.xml
+	find . -type d -empty -delete
 
 # Target for generating coverage report
 cov:
@@ -51,12 +45,16 @@ cov-xml:
 
 # Target for installing project dependencies
 deps:
-	$(PIP) install -r requirements.txt -r requirements-dev.txt
+	$(PIP) install --upgrade pip setuptools wheel -r requirements.txt -r requirements-dev.txt
 
 # Target for installing the project in editable mode
 dev:
 	$(PIP) install -e .
 
+# Build documentation.
+docs:
+	$(MAKE) -C ./docs
+
 # Target for fixing linting issues.
 fix:
 	$(PYTHON) -m ruff check --fix
@@ -80,8 +78,8 @@ test:
 
 # Target for uninstalling the project
 uninstall:
-	$(PIP) uninstall -y $(NAME)
+	$(PIP) uninstall $(NAME)
 
 # Target for displaying the project version
 version:
-	$(PYTHON) -m setuptools_scm
+	@$(PYTHON) -m setuptools_scm

README.md

@@ -40,8 +40,6 @@ with Client(api_key="my-secret-api-key", url="https://example.com") as client:
     print(client)
 ```
 
-
-
 ## Contributing
 
 We welcome contributions to the Posit SDK for Python! If you would like to contribute, see the [CONTRIBUTING](CONTRIBUTING.md) guide for instructions.

docs/.gitignore

@@ -0,0 +1,8 @@
+_extensions/
+_inv/
+_site/
+.quarto/
+objects.json
+reference/
+
+/.quarto/

docs/Makefile

@@ -0,0 +1,33 @@
+.DEFAULT_GOAL := all
+
+# Command aliases
+QUARTO=quarto
+QUARTODOC=quartodoc
+
+# Environment variables
+CURRENT_YEAR := $(shell date +%Y)
+VERSION := $(shell make -C ../ version)
+export CURRENT_YEAR VERSION
+
+.PHONY: clean build deps preview
+
+all: deps api build
+
+api: deps
+	$(QUARTODOC) build
+	$(QUARTODOC) interlinks
+	cp -r _extensions/ reference/_extensions	# Required to render footer
+
+build: api
+	$(QUARTO) render
+
+clean:
+	rm -rf _extensions _inv _site .quarto reference objects.json
+	find . -type d -empty -delete
+
+deps:
+	$(QUARTO) add --no-prompt posit-dev/[email protected]
+	$(QUARTO) add --no-prompt machow/quartodoc
+
+preview: api
+	$(QUARTO) preview