Skip to content

Fixes all Four #65 #66 #67 #68 #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
houfu merged 8 commits into from
Oct 14, 2025
Merged

Fixes all Four #65 #66 #67 #68 #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
e4e89a3
Fix: Trigger docs build only on release publish
abbasabro Oct 11, 2025
6cf037c
Fix #66
abbasabro Oct 12, 2025
23b3e36
Fix #67
abbasabro Oct 12, 2025
06475ff
Fix #68
abbasabro Oct 12, 2025
8ab27ea
Adding the index.html for fix#67
abbasabro Oct 12, 2025
dd154da
Delete docs directory
abbasabro Oct 12, 2025
76b586b
Apply suggestions from code review
houfu Oct 14, 2025
2f352db
Update CONTRIBUTING.md
houfu Oct 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 30 additions & 3 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,8 @@ name: website

# build the documentation whenever there are new commits on main
on:
push:
branches:
- main
release:
types: [published]
# Alternative: only build for tags.
# tags:
# - '*'
Expand All @@ -30,6 +29,34 @@ jobs:
cache-dependency-glob: "uv.lock"
- name: Install the project
run: uv sync --all-extras --dev
- name: Extract version from tag
run: |
VERSION=${GITHUB_REF#refs/tags/}
echo "VERSION=$VERSION" >> $GITHUB_ENV
echo "Building docs for version: $VERSION"
- name: Create version wrapper
run: |
mv docs generated-docs
mkdir -p docs
cat > docs/index.html << 'EOF'
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Documentation</title>
<meta http-equiv="refresh" content="0; url=./generated-docs/index.html">
</head>
<body>
<div style="background: #e3f2fd; padding: 12px; text-align: center; border-bottom: 2px solid #2196f3; font-weight: bold;">
Documentation for version $VERSION
</div>
<h1>Documentation for version $VERSION</h1>
<p>Redirecting to <a href="./generated-docs/index.html">documentation</a>...</p>
</body>
</html>
EOF
mv generated-docs docs/

- run: uv run pdoc -o docs/ redlines
- uses: actions/upload-pages-artifact@v3
with:
Expand Down
31 changes: 31 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,37 @@ and respectful in your tone.
To preview documentation, you can clone the project, install development dependencies, and then run `pdoc redlines` to
see your changes.

## Documentation

Our documentation is automatically generated from source code using `pdoc`.

### How It Works
- Documentation builds automatically **when a new release is published**.
- The release tag (for example `v1.2.3`) is extracted by the CI workflow and exposed to the build as the `VERSION` environment variable.
- The version number is displayed in the published documentation.

### To Update Documentation
1. Make code changes and update docstrings as needed.
2. Create and publish a new release on GitHub (use tags like `vMAJOR.MINOR.PATCH`).
3. The documentation workflow will run automatically and rebuild the docs for that release.
4. Check the deployed docs to verify the version banner and content.

### Manual Documentation Build (for testing)
To build docs locally before releasing:

```bash
# install pdoc locally
pip install pdoc

# generate HTML into docs/
pdoc --html --output-dir docs/ your_package_name

# preview locally
cd docs
python -m http.server 8000
# then open http://localhost:8000 in your browser
```

## Styleguides

For code, we use the [Black formatter](https://black.readthedocs.io/en/stable/index.html). Please be encouraged to use
Expand Down