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,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

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

docs/_quarto.yml

@@ -0,0 +1,107 @@
+project:
+  type: website
+
+website:
+  title: "Posit SDK <small>{{< env VERSION >}}</small>"
+  bread-crumbs: true
+  favicon: "_extensions/posit-dev/posit-docs/assets/images/favicon.svg"
+  navbar:
+    pinned: true
+    logo: "_extensions/posit-dev/posit-docs/assets/images/posit-icon-fullcolor.svg"
+    logo-alt: "Posit Documentation"
+    left:
+      - text: Installation
+        file: installation.qmd
+      - text: Quick Start
+        file: quickstart.qmd
+      - text: API
+        file: reference/index.qmd
+    right:
+      - icon: "list"
+        aria-label: 'Drop-down menu for additional Posit resources'
+        menu:
+        - text: "docs.posit.co"
+          href: "https://docs.posit.co"
+        - text: "Posit Support"
+          href: "https://support.posit.co/hc/en-us/"
+  page-footer:
+    left: |
+      Copyright &copy; 2000-{{< env CURRENT_YEAR >}} Posit Software, PBC. All Rights Reserved.
+    center: |
+      Posit PRODUCT {{< env VERSION >}}
+    right:
+      - icon: question-circle-fill
+        aria-label: 'Link to Posit Support'
+        href: "https://support.posit.co/hc/en-us"
+      - icon: lightbulb-fill
+        aria-label: 'Link to Posit Solutions'
+        href: "https://solutions.posit.co/"
+      - text: "<img alt='Link to Posit Documentation' src='_extensions/posit-dev/posit-docs/assets/images/posit-guide-ltmd.svg' id='footer-right-logo'>"
+        href: "https://docs.posit.co/"
+      - text: "<img alt='Link to main Posit site' src='_extensions/posit-dev/posit-docs/assets/images/posit-icon-fullcolor.svg' id='footer-right-posit-logo'>"
+        href: "https://posit.co/"
+  search:
+    copy-button: true
+    show-item-context: true
+
+filters:
+  - interlinks
+
+format:
+  html:
+    theme:
+      light:
+        - _extensions/posit-dev/posit-docs/theme.scss
+      dark:
+        - _extensions/posit-dev/posit-docs/theme-dark.scss
+    include-in-header: "_extensions/posit-dev/posit-docs/assets/_analytics.html"
+    link-external-icon: true
+    link-external-newwindow: true
+    toc: true
+    toc-expand: true
+
+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 professional products. It's lightweight and expressive.
+
+Welcome to the Posit 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 available 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 the Posit SDK
+
+Use the following command to install the Posit SDK:
+
+```bash
+$ pip install posit-sdk
+```
+
+The SDK is now installed. Check out the [Quickstart](./quickstart.qmd) section.

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 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 not provided by during 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 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](./reference/index.qmd) for more information.

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"