Skip to content

Commit 7b26f83

Browse files
XkunWXkunW
authored
Merge pull request #92 from VectorInstitute/add_multiversion_docs_support
Add support for multiversion docs hosted via github pages
2 parents 14a7776 + e41b9b3 commit 7b26f83

File tree

6 files changed

+450
-9
lines changed

6 files changed

+450
-9
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 79 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,6 @@ on:
77
push:
88
branches:
99
- main
10-
- develop
1110
paths:
1211
- .pre-commit-config.yaml
1312
- .github/workflows/docs.yml
@@ -24,7 +23,6 @@ on:
2423
pull_request:
2524
branches:
2625
- main
27-
- develop
2826
paths:
2927
- .pre-commit-config.yaml
3028
- .github/workflows/docs.yml
@@ -38,13 +36,24 @@ on:
3836
- mkdocs.yml
3937
- '**.png'
4038
- '**.svg'
39+
release:
40+
types: [published]
41+
# Allow manual trigger
42+
workflow_dispatch:
43+
inputs:
44+
version:
45+
description: 'Version to deploy (e.g., 0.5.0, latest)'
46+
required: true
47+
default: 'latest'
4148

4249
jobs:
4350
build:
4451
runs-on: ubuntu-latest
4552
steps:
4653
- name: Checkout code
4754
uses: actions/checkout@v4.2.2
55+
with:
56+
fetch-depth: 0 # Fetch all history for proper versioning
4857

4958
- name: Install uv
5059
uses: astral-sh/setup-uv@v5
@@ -75,11 +84,27 @@ jobs:
7584

7685
deploy:
7786
needs: build
78-
if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
87+
if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch' || github.event_name == 'release'
7988
runs-on: ubuntu-latest
8089
steps:
8190
- name: Checkout code
8291
uses: actions/checkout@v4.2.2
92+
with:
93+
fetch-depth: 0 # Fetch all history for proper versioning
94+
95+
- name: Install uv
96+
uses: astral-sh/setup-uv@v5
97+
with:
98+
version: "0.5.21"
99+
enable-cache: true
100+
101+
- name: Set up Python
102+
uses: actions/setup-python@v5
103+
with:
104+
python-version-file: ".python-version"
105+
106+
- name: Install the project
107+
run: uv sync --all-extras --group docs
83108

84109
- name: Configure Git Credentials
85110
run: |
@@ -95,8 +120,54 @@ jobs:
95120
- name: Ensure .nojekyll exists
96121
run: touch site/.nojekyll
97122

98-
- name: Deploy to Github pages
99-
uses: JamesIves/github-pages-deploy-action@v4.7.3
100-
with:
101-
branch: gh-pages
102-
folder: site
123+
- name: Determine version
124+
id: version
125+
run: |
126+
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
127+
# Use the version provided in the workflow dispatch
128+
echo "VERSION=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
129+
echo "VERSION_ALIAS=latest" >> $GITHUB_OUTPUT
130+
elif [[ "${{ github.event_name }}" == "release" ]]; then
131+
# Use the tag from the release
132+
VERSION="${{ github.ref_name }}"
133+
# Remove 'v' prefix if present
134+
VERSION="${VERSION#v}"
135+
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
136+
echo "VERSION_ALIAS=latest" >> $GITHUB_OUTPUT
137+
elif [[ "${{ github.event_name }}" == "push" && "${{ github.ref }}" == "refs/heads/main" ]]; then
138+
# For pushes to main, tag as "main"
139+
echo "VERSION=main" >> $GITHUB_OUTPUT
140+
# No alias for main
141+
echo "VERSION_ALIAS=" >> $GITHUB_OUTPUT
142+
else
143+
# Get version from pyproject.toml as fallback
144+
VERSION=$(grep -m 1 '^version = ' pyproject.toml | sed 's/^version = "\(.*\)"$/\1/')
145+
echo "VERSION=$VERSION" >> $GITHUB_OUTPUT
146+
echo "VERSION_ALIAS=latest" >> $GITHUB_OUTPUT
147+
fi
148+
149+
- name: Deploy docs with mike
150+
run: |
151+
VERSION=${{ steps.version.outputs.VERSION }}
152+
ALIAS=${{ steps.version.outputs.VERSION_ALIAS }}
153+
154+
# Add a temporary remote to fetch gh-pages if it exists
155+
git remote add temp https://github.com/${{ github.repository }}.git || true
156+
git fetch temp gh-pages || true
157+
158+
DEPLOY_ARGS="--push --update-aliases $VERSION"
159+
160+
if [[ ! -z "$ALIAS" ]]; then
161+
DEPLOY_ARGS="$DEPLOY_ARGS $ALIAS"
162+
fi
163+
164+
echo "Running: mike deploy $DEPLOY_ARGS"
165+
mike deploy $DEPLOY_ARGS
166+
167+
# Set default version to latest only if we're deploying a version with the latest alias
168+
if [[ ! -z "$ALIAS" && "$ALIAS" == "latest" ]]; then
169+
mike set-default --push latest
170+
fi
171+
172+
# Remove the temporary remote
173+
git remote remove temp || true

‎docs/contributing.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Contributing to Vector Inference
2+
3+
Thank you for your interest in contributing to Vector Inference! This guide will help you get started with development, testing, and documentation contributions.
4+
5+
## Development Setup
6+
7+
### Prerequisites
8+
9+
- Python 3.10 or newer
10+
- [uv](https://github.com/astral-sh/uv) for dependency management
11+
12+
### Setting Up Development Environment
13+
14+
1. Clone the repository:
15+
```bash
16+
git clone https://github.com/VectorInstitute/vector-inference.git
17+
cd vector-inference
18+
```
19+
20+
2. Install development dependencies:
21+
```bash
22+
uv sync --all-extras --group dev
23+
```
24+
25+
3. Install pre-commit hooks:
26+
```bash
27+
pre-commit install
28+
```
29+
30+
!!! tip "Using Virtual Environments"
31+
If you prefer using virtual environments, you can use `uv venv` to create one:
32+
```bash
33+
uv venv
34+
source .venv/bin/activate
35+
```
36+
37+
## Development Workflow
38+
39+
### Code Style and Linting
40+
41+
We use several tools to ensure code quality:
42+
43+
- **ruff** for linting and formatting
44+
- **mypy** for type checking
45+
46+
You can run these tools with:
47+
48+
```bash
49+
# Linting
50+
uv run ruff check .
51+
52+
# Type checking
53+
uv run mypy
54+
55+
# Format code
56+
uv run ruff format .
57+
```
58+
59+
!!! note "Pre-commit Hooks"
60+
The pre-commit hooks will automatically run these checks before each commit.
61+
If the hooks fail, you will need to fix the issues before you can commit.
62+
63+
### Testing
64+
65+
All new features and bug fixes should include tests. We use pytest for testing:
66+
67+
```bash
68+
# Run all tests
69+
uv run pytest
70+
71+
# Run tests with coverage
72+
uv run pytest --cov=vec_inf
73+
```
74+
75+
## Documentation
76+
77+
### Documentation Setup
78+
79+
Install the documentation dependencies:
80+
81+
```bash
82+
uv sync --group docs
83+
```
84+
85+
### Building Documentation
86+
87+
Build and serve the documentation locally:
88+
89+
```bash
90+
# Standard build
91+
mkdocs build
92+
93+
# Serve locally with hot-reload
94+
mkdocs serve
95+
```
96+
97+
### Versioned Documentation
98+
99+
Vector Inference uses [mike](https://github.com/jimporter/mike) to manage versioned documentation. This allows users to access documentation for specific versions of the library.
100+
101+
#### Available Versions
102+
103+
The documentation is available in multiple versions:
104+
105+
- `latest` - Always points to the most recent stable release
106+
- Version-specific documentation (e.g., `0.5.0`, `0.4.0`)
107+
108+
#### Versioning Strategy
109+
110+
Our versioning strategy follows these rules:
111+
112+
1. Each release gets its own version number matching the package version (e.g., `0.5.0`)
113+
2. The `latest` alias always points to the most recent stable release
114+
3. Documentation is automatically deployed when changes are pushed to the main branch
115+
116+
#### Working with Mike Locally
117+
118+
To preview or work with versioned documentation:
119+
120+
```bash
121+
# Build and deploy a specific version to your local gh-pages branch
122+
mike deploy 0.5.0
123+
124+
# Add an alias for the latest version
125+
mike deploy 0.5.0 latest
126+
127+
# Set the default version to redirect to
128+
mike set-default latest
129+
130+
# View the deployed versions
131+
mike list
132+
133+
# Serve the versioned documentation locally
134+
mike serve
135+
```
136+
137+
#### Automatic Documentation Deployment
138+
139+
Documentation is automatically deployed through GitHub Actions:
140+
141+
- On pushes to `main`, documentation is deployed with the version from `pyproject.toml` and the `latest` alias
142+
- Through manual trigger in the GitHub Actions workflow, where you can specify the version to deploy
143+
144+
!!! info "When to Update Documentation"
145+
- When adding new features
146+
- When changing existing APIs
147+
- When fixing bugs that affect user experience
148+
- When improving explanations or examples
149+
150+
## Pull Request Process
151+
152+
1. **Fork the repository** and create your branch from `main`
153+
2. **Make your changes** and add appropriate tests
154+
3. **Ensure tests pass** and code meets style guidelines
155+
4. **Write clear documentation** for your changes
156+
5. **Submit a pull request** with a clear description of the changes
157+
158+
!!! important "Checklist Before Submitting PR"
159+
- [ ] All tests pass
160+
- [ ] Code is formatted with ruff
161+
- [ ] Type annotations are correct
162+
- [ ] Documentation is updated
163+
- [ ] Commit messages are clear and descriptive
164+
165+
## Release Process
166+
167+
1. Update version in `pyproject.toml`
168+
2. Update changelogs and documentation as needed
169+
3. Create a new tag and release on GitHub
170+
4. Documentation for the new version will be automatically deployed
171+
172+
## License
173+
174+
By contributing to Vector Inference, you agree that your contributions will be licensed under the project's [MIT License](https://github.com/VectorInstitute/vector-inference/blob/main/LICENSE).

0 commit comments

Comments
 (0)