Skip to content

Commit a345fcb

Browse files
alexluck-siftalexluck-sift
authored
Python/mkdocs init (#257)
1 parent 257cc35 commit a345fcb

30 files changed

Lines changed: 935 additions & 22 deletions

‎.github/workflows/python_build_docs.yml‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
name: Build and Deploy Python Docs (Dev)
2+
3+
on:
4+
pull_request:
5+
types: [opened, synchronize, closed]
6+
paths:
7+
- 'python/docs/**'
8+
- 'python/lib/**'
9+
- 'python/mkdocs.yml'
10+
- 'python/pyproject.toml'
11+
workflow_dispatch:
12+
inputs:
13+
deploy_to_dev:
14+
description: 'Deploy to dev alias using commit hash as version'
15+
required: false
16+
default: true
17+
type: boolean
18+
19+
jobs:
20+
build_docs:
21+
if: github.event.action != 'closed'
22+
runs-on: ubuntu-latest
23+
permissions:
24+
contents: write
25+
steps:
26+
- name: Checkout code
27+
uses: actions/checkout@v4
28+
with:
29+
fetch-depth: 1
30+
31+
- name: Set up Python
32+
uses: actions/setup-python@v4
33+
with:
34+
python-version: '3.11'
35+
36+
- name: Install dependencies
37+
run: |
38+
cd python
39+
pip install -e .[docs,development]
40+
41+
- name: Extract version
42+
id: version
43+
run: |
44+
# Use commit hash as version for dev deployments
45+
VERSION=$(git rev-parse --short HEAD)
46+
47+
if [[ "${{ github.event_name }}" == "pull_request" ]]; then
48+
# Use PR number as alias for PR deployments
49+
ALIAS="pr-${{ github.event.number }}"
50+
else
51+
# Use 'dev' for manual workflow dispatch
52+
ALIAS="dev"
53+
fi
54+
55+
echo "version=$VERSION" >> $GITHUB_OUTPUT
56+
echo "alias=$ALIAS" >> $GITHUB_OUTPUT
57+
echo "Dev deployment - Version: $VERSION, Alias: $ALIAS"
58+
59+
- name: Fetch gh-pages branch
60+
run: git fetch origin gh-pages --depth=1
61+
62+
- name: Configure Git
63+
run: |
64+
git config --global user.name "github-actions[bot]"
65+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
66+
67+
- name: Deploy docs with mike
68+
run: |
69+
cd python
70+
# Deploy dev/PR docs with hidden property to hide from version dropdown
71+
mike deploy ${{ steps.version.outputs.alias }} --push --update-aliases --prop-set hidden=true
72+
env:
73+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
74+
75+
cleanup_docs:
76+
if: github.event.action == 'closed'
77+
runs-on: ubuntu-latest
78+
permissions:
79+
contents: write
80+
steps:
81+
- name: Checkout code
82+
uses: actions/checkout@v4
83+
with:
84+
fetch-depth: 1
85+
86+
- name: Set up Python
87+
uses: actions/setup-python@v4
88+
with:
89+
python-version: '3.11'
90+
91+
- name: Install dependencies
92+
run: |
93+
cd python
94+
pip install -e .[docs,development]
95+
96+
- name: Fetch gh-pages branch
97+
run: git fetch origin gh-pages --depth=1
98+
99+
- name: Configure Git
100+
run: |
101+
git config --global user.name "github-actions[bot]"
102+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
103+
104+
- name: Delete PR docs
105+
run: |
106+
cd python
107+
PR_ALIAS="pr-${{ github.event.number }}"
108+
echo "Deleting docs for: $PR_ALIAS"
109+
110+
# Check if the PR docs exist before trying to delete
111+
if mike list | grep -q "$PR_ALIAS"; then
112+
mike delete "$PR_ALIAS" --push
113+
echo "Successfully deleted docs for $PR_ALIAS"
114+
else
115+
echo "No docs found for $PR_ALIAS, nothing to delete"
116+
fi
117+
env:
118+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎.github/workflows/python_release.yaml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,4 +87,89 @@ jobs:
8787
echo "Uploading archive: $archive"
8888
gh release upload "$TAG_NAME" "$archive" --clobber
8989
done
90+
91+
deploy-docs:
92+
name: Deploy Documentation
93+
needs: publish-to-pypi
94+
runs-on: ubuntu-latest
95+
permissions:
96+
contents: write
97+
steps:
98+
- name: Checkout code
99+
uses: actions/checkout@v4
100+
with:
101+
fetch-depth: 1
102+
103+
- name: Set up Python
104+
uses: actions/setup-python@v4
105+
with:
106+
python-version: '3.11'
107+
108+
- name: Install dependencies
109+
run: |
110+
cd python
111+
pip install -e .[docs,development]
112+
113+
- name: Extract version and check if stable
114+
id: version
115+
run: |
116+
# Extract version from tag (everything after 'python/')
117+
FULL_VERSION=${GITHUB_REF#refs/tags/python/}
118+
echo "Full version from tag: $FULL_VERSION"
119+
120+
# Extract major.minor from version (drop patch)
121+
if [[ "$FULL_VERSION" =~ ^v?([0-9]+)\.([0-9]+)\.[0-9]+(.*)?$ ]]; then
122+
MAJOR=${BASH_REMATCH[1]}
123+
MINOR=${BASH_REMATCH[2]}
124+
SUFFIX=${BASH_REMATCH[3]}
125+
VERSION="v${MAJOR}.${MINOR}"
126+
127+
# Check if this is a stable release (no suffix like -alpha, -beta, -rc)
128+
if [[ -z "$SUFFIX" ]]; then
129+
# Stable release - use 'latest' alias and make visible
130+
ALIAS="latest"
131+
HIDDEN="false"
132+
echo "Stable release detected: $FULL_VERSION -> $VERSION"
133+
else
134+
# Pre-release (alpha, beta, rc) - no 'latest' alias and hide from dropdown
135+
VERSION="${VERSION}${SUFFIX}"
136+
ALIAS=""
137+
HIDDEN="true"
138+
echo "Pre-release detected: $FULL_VERSION -> $VERSION"
139+
fi
140+
else
141+
echo "Error: Could not parse version format: $FULL_VERSION"
142+
exit 1
143+
fi
144+
145+
echo "version=$VERSION" >> $GITHUB_OUTPUT
146+
echo "alias=$ALIAS" >> $GITHUB_OUTPUT
147+
echo "hidden=$HIDDEN" >> $GITHUB_OUTPUT
148+
echo "Final - Version: $VERSION, Alias: $ALIAS, Hidden: $HIDDEN"
149+
150+
- name: Fetch gh-pages branch
151+
run: git fetch origin gh-pages --depth=1
152+
153+
- name: Configure Git
154+
run: |
155+
git config --global user.name "github-actions[bot]"
156+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
157+
158+
- name: Deploy docs with mike
159+
run: |
160+
cd python
161+
VERSION="${{ steps.version.outputs.version }}"
162+
ALIAS="${{ steps.version.outputs.alias }}"
163+
HIDDEN="${{ steps.version.outputs.hidden }}"
90164
165+
# Always deploy the full version first, but hide it
166+
echo "Deploying full version $FULL_VERSION (hidden)"
167+
mike deploy "$FULL_VERSION" --push --prop-set hidden=true
168+
169+
if [[ "$HIDDEN" == "false" ]]; then
170+
# Stable release: deploy abbreviated version with latest alias, visible in dropdown
171+
echo "Deploying stable release $VERSION with $ALIAS alias"
172+
mike deploy "$VERSION" "$ALIAS" --push --update-aliases
173+
fi
174+
env:
175+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎python/docs/index.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Sift Python Client Library
2+
Welcome to the official Python client library for Sift! This library provides a high-level Python API on top of Sift's protocol buffers, designed to ergonomically interface with the Sift gRPC API and simplify the process of streaming data.
3+
4+
Sift provides official client libraries for select languages, designed to simplify the process of streaming data over gRPC. These client libraries utilize ingestion-config-based streaming to facilitate data transmission.
5+
6+
Check out the [repository](https://github.com/sift-stack/sift) for a list of all available client libraries.
7+
8+
## Installation
9+
10+
To install the Sift Python library:
11+
12+
```bash
13+
pip install sift-stack-py
14+
```
15+
16+
## API Documentation
17+
18+
This documentation covers two Python APIs for interacting with Sift:
19+
20+
### Sift Py API
21+
22+
The original low-level Python API that provides direct access to Sift's protocol buffer interfaces.
23+
24+
Browse the [**Sift Py API**][sift_py] section for complete reference documentation.
25+
26+
**Use this API if you need:**
27+
28+
- Direct protocol buffer access
29+
- Fine-grained control over gRPC connections
30+
- Legacy compatibility with existing code
31+
32+
### Sift Client API (New)
33+
34+
!!! warning
35+
The Sift Client is experimental and is subject to change.
36+
37+
38+
The modern, high-level client library that provides all the ergonomic features missing from the original API. This new client offers intuitive Python interfaces, strong type safety, automatic connection management, and both synchronous and asynchronous support.
39+
40+
Explore the [**Sift Client API (New)**][sift_client] section for the complete API reference.
41+
42+
**Key improvements over Sift Py:**
43+
44+
- **Ergonomic Design** - Pythonic interfaces instead of raw protocol buffers
45+
- **Type Safety** - Full type hints and Pydantic model validation
46+
- **Dual APIs** - Both sync and async support for all operations
47+
- **Auto Connection Management** - No manual gRPC connection handling
48+
- **Rich Object Models** - Immutable types with convenient methods
49+
- **Modern Patterns** - Context managers, iterators, and Python best practices
50+
51+
52+
## Getting help
53+
54+
- **API Reference** - Browse the complete API documentation in the navigation
55+
- **Examples** - Check out code examples throughout the documentation
56+
- **GitHub** - Visit our [repository](https://github.com/sift-stack/sift) for issues and contributions
57+
58+
## What's next?
59+
60+
Ready to dive deeper? Explore the API documentation to learn about:
61+
62+
- **Sift Resources** - Creating, updating, and organizing your assets and other data
63+
- **Data Streaming** - Efficient methods for ingesting data
64+
- **Advanced Filtering** - Powerful query capabilities
65+
- **Error Handling** - Best practices for robust applications
66+
- **Performance Optimization** - Tips for high-throughput scenarios
67+
68+
Get started by exploring the API reference in the navigation menu!

‎python/docs/overrides/main.html‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{% extends "base.html" %}
2+
3+
{% block outdated %}
4+
You're not viewing the latest version.
5+
<a href="{{ '../' ~ base_url }}">
6+
7+
8+
<strong>Click here to go to latest.</strong>
9+
</a>
10+
{% endblock %}

‎python/docs/overrides/partials/logo.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
<img id='logo_dark_mode' src='{{ config.theme.logo_dark_mode | url }}' alt='logo'>
2+
<img id='logo_light_mode' src='{{ config.theme.logo_light_mode | url }}' alt='logo'>

0 commit comments

Comments
 (0)