docs: add quartodoc website for documentation

.github/workflows/ci.yaml

@@ -50,3 +50,17 @@ jobs:
           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

Makefile

@@ -13,20 +13,7 @@ else
 PIP := pip3
 endif
 
-.PHONY:
-	build
-	clean
-	cov
-	default
-	deps
-	dev
-	fmt
-	fix
-	install
-	lint
-	test
-	uninstall
-	version
+.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
@@ -64,6 +51,10 @@ deps:
 dev:
 	$(PIP) install -e .
 
+# Build documentation.
+docs:
+	$(MAKE) -C ./docs
+
 # Target for fixing linting issues.
 fix:
 	$(PYTHON) -m ruff check --fix
@@ -87,7 +78,7 @@ test:
 
 # Target for uninstalling the project
 uninstall:
-	$(PIP) uninstall -y $(NAME)
+	$(PIP) uninstall $(NAME)
 
 # Target for displaying the project version
 version:

docs/.gitignore

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

docs/Makefile

@@ -0,0 +1,27 @@
+.DEFAULT_GOAL := all
+
+# Command aliases
+QUARTO=quarto
+QUARTODOC=quartodoc
+
+# Targets
+.PHONY: clean build deps preview
+
+all: deps build
+
+build:
+	$(QUARTODOC) build
+	$(QUARTODOC) interlinks
+	$(QUARTO) render
+
+clean:
+	rm -rf _extensions _inv _site .quarto reference objects.json
+	find . -type d -empty -delete
+
+deps:
+	$(QUARTO) add --no-prompt machow/quartodoc
+
+preview:
+	$(QUARTODOC) build
+	$(QUARTODOC) interlinks
+	$(QUARTO) preview

docs/_quarto.yml

@@ -0,0 +1,68 @@
+project:
+  type: website
+
+website:
+  title: "Posit SDK"
+  navbar:
+    left:
+      - text: Installation
+        file: installation.qmd
+      - text: Quick Start
+        file: quickstart.qmd
+      - text: API
+        file: reference/index.qmd
+
+filters:
+  - interlinks
+
+format:
+  html:
+    theme: cosmo
+    toc: true
+    page-layout: full
+
+interlinks:
+  sources:
+    python:
+      url: https://docs.python.org/3/
+    requests:
+      url: https://requests.readthedocs.io/en/latest/
+
+quartodoc:
+  title: API Reference
+  style: pkgdown
+  dir: reference
+  package: posit
+  render_interlinks: true
+  options:
+      include_classes: true
+      include_functions: true
+      include_empty: true
+  sections:
+    - title: Clients
+      package: posit
+      desc: >
+        The `Client` is the entrypoint for each Posit product. Initialize a `Client` to get started.
+      contents:
+        - name: connect.Client
+          members:
+            # methods
+            - request
+            - get
+            - post
+            - put
+            - patch
+            - delete
+    - title: Posit Connect Resources
+      package: posit
+      contents:
+        - connect.bundles
+        - connect.content
+        - connect.permissions
+        - connect.tasks
+        - connect.users
+    - title: Posit Connect Metrics
+      package: posit
+      contents:
+        - connect.metrics
+        - connect.metrics.usage

docs/index.qmd

@@ -0,0 +1,7 @@
+---
+title: "Posit SDK for Python"
+---
+
+> A Pythonic interface for developers to work with Posit's professional products. It's lightweight and expressive.
+
+Welcome to Posit's SDK for Python documentation! Get started with [Installation](./installation.qmd) and then check out [Quickstart](./quickstart.qmd). A full API reference is available in the [API](./reference/index.qmd) section.

docs/installation.qmd

@@ -0,0 +1,27 @@
+---
+title: "Installation"
+format: html
+toc: true
+toc-title: "Contents"
+toc-depth: 2
+---
+
+# Python Version
+
+We recommend using the latest version of Python avaiable to you. The Posit SDK supports Python 3.8 and newer.
+
+# Dependencies
+
+These dependencies are installed automatically during installation.
+
+- [Requests](https://requests.readthedocs.io/en/latest/) provides the HTTP layer.
+
+# Install Posit's SDK
+
+Use the following command to install Posit's SDK
+
+```bash
+$ pip install posit-SDK
+```
+
+The SDK is now installed. Check out the [Quickstart](./quickstart.qmd).

docs/quickstart.qmd

@@ -0,0 +1,56 @@
+---
+title: "Quickstart"
+format: html
+toc: true
+toc-title: "Contents"
+toc-depth: 2
+---
+
+# Setup
+
+After [installing](./installation.qmd) the SDK, you need to import it. Here's a simple example of to get you started.
+
+```python
+>>> import posit
+```
+
+# Basic Usage
+
+## Initialize a Client
+
+To get started, initialize a Client to work with your Posit products. For this example, we will work with Posit Connect.
+
+::: {.callout-warning}
+Keeping your API key secret is essential to protect your application's security, prevent unauthorized access and usage, and ensure data privacy and regulatory compliance. By default, the API key is read from the `CONNECT_API_KEY` environment variable when it isn't provided in the Client initialization.
+:::
+
+
+```python
+>>> from posit import connect
+>>> client = connect.Client(api_key="btOVKLXjt8CoGP2gXvSuTqu025MJV4da", url="https://connect.example.com")
+```
+
+## Who am I?
+
+Your API key is your secret identity. Now that we're connected, let's double check our username.
+
+```python
+>>> client.me.username
+'gandalf'
+```
+
+## How much content do I have access to?
+
+One of the best features of Connect is the ability to share incredible content with your peers. Let's see just how much content we have access to!
+
+```python
+>>> client.content.count()
+5754
+```
+
+Voilà! I have a whopping 5,754 pieces of content to browse.
+
+
+# Next Steps
+
+Check out the [API](./reference/index.qmd) for a full API reference.

requirements-dev.txt

@@ -5,6 +5,7 @@ pandas
 pre-commit
 pyjson5
 pytest
+quartodoc
 responses
 ruff
 setuptools

src/posit/__init__.py

@@ -1 +1,5 @@
 """The Posit SDK."""
+
+from . import connect  # noqa
+
+__all__ = "connect"