Skip to content

Commit 3378fd8

Browse files
lord-haffilord-haffi
authored
🚀📄Deploy Documentation to GitHub Pages - instead of RTD (#764)
1 parent 3e8e940 commit 3378fd8

6 files changed

Lines changed: 136 additions & 54 deletions

File tree

‎.github/workflows/docs_latest.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Build documentation /latest
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
# Allows you to run this workflow manually from the Actions tab
8+
workflow_dispatch:
9+
10+
jobs:
11+
build:
12+
name: 🚀📄 Build and deploy documentation to GitHub Pages
13+
# This setup is inspired by
14+
# https://github.com/KernelTuner/kernel_tuner/blob/master/.github/workflows/docs-on-release.yml
15+
runs-on: ${{ matrix.os }}
16+
strategy:
17+
matrix:
18+
python-version: ["3.12"]
19+
os: [ubuntu-latest]
20+
steps:
21+
- uses: actions/setup-python@v4
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
- name: Checkout
25+
uses: actions/checkout@v4
26+
with:
27+
fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install -r requirements.txt
32+
# Note: The sphinx action below can only install a single requirements file.
33+
- name: Write version to conf.py
34+
run: |
35+
echo -e "version = release = \"latest\"\n" | cat - docs/conf.py > /tmp/conf.py && mv /tmp/conf.py docs/conf.py
36+
- name: Build the documentation
37+
uses: sphinx-notes/pages@v2
38+
# Note: This action has a newer version (v3 atm), but it doesn't has the feature to specify the target path.
39+
# We need that in order to be able to store (and deploy) multiple versions of the documentation.
40+
with:
41+
requirements_path: docs/requirements.txt
42+
documentation_path: docs/
43+
target_path: latest/
44+
target_branch: gh-pages
45+
sphinx_options: -W -j auto
46+
- name: Push changes
47+
uses: ad-m/github-push-action@master
48+
with:
49+
github_token: ${{ secrets.GITHUB_TOKEN }}
50+
branch: gh-pages

‎.github/workflows/python-publish.yml‎

Lines changed: 54 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ jobs:
2828
- name: Run the Tests
2929
run: |
3030
tox -e tests
31-
generate:
31+
json_schemas:
3232
name: Generate JSON-Schemas
3333
runs-on: ubuntu-latest
3434
needs: tests
@@ -70,6 +70,58 @@ jobs:
7070
env:
7171
GITHUB_TOKEN: ${{ secrets.BO4E_PYTHON_GENERATE_SCHEMAS }} # this token expires on 2024-10-09
7272
VERSION: ${{ github.ref_name }}
73+
docs:
74+
name: 🚀📄 Build and deploy documentation to GitHub Pages
75+
# This setup is inspired by
76+
# https://github.com/KernelTuner/kernel_tuner/blob/master/.github/workflows/docs-on-release.yml
77+
runs-on: ubuntu-latest
78+
needs: tests
79+
steps:
80+
- uses: actions/checkout@v4
81+
with:
82+
fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
83+
- name: Set up Python
84+
uses: actions/setup-python@v5
85+
with:
86+
python-version: ${{ matrix.python-version }}
87+
- name: Install dependencies
88+
run: |
89+
python -m pip install --upgrade pip
90+
pip install -r requirements.txt
91+
# Note: The sphinx action below can only install a single requirements file.
92+
- name: Write version to conf.py
93+
run: |
94+
echo -e "version = release = \"${{ github.ref_name }}\"\n" | cat - docs/conf.py > /tmp/conf.py
95+
mv /tmp/conf.py docs/conf.py
96+
- name: Build the documentation
97+
uses: sphinx-notes/pages@v2
98+
# Note: This action has a newer version (v3 atm), but it doesn't has the feature to specify the target path.
99+
# We need that in order to be able to store (and deploy) multiple versions of the documentation.
100+
with:
101+
requirements_path: docs/requirements.txt
102+
documentation_path: docs/
103+
target_path: ${{ github.ref_name }}
104+
target_branch: gh-pages
105+
sphinx_options: -W -j auto
106+
- id: latest_bo4e
107+
name: Get latest BO4E release tag
108+
uses: pozetroninc/github-action-get-latest-release@master
109+
with:
110+
repository: ${{ github.repository }}
111+
token: ${{ secrets.GITHUB_TOKEN }}
112+
- name: Redirect stable to new release if the new release is marked as latest
113+
if: steps.latest_bo4e.outputs.release == github.ref_name
114+
run: |
115+
echo "Redirecting stable to new version ${{ github.ref_name }}"
116+
rm -rf stable
117+
ln -s ${{ github.ref_name }} stable
118+
git add stable
119+
git commit -m "Redirect stable to new version ${{ github.ref_name }}"
120+
- name: Push changes
121+
uses: ad-m/github-push-action@master
122+
with:
123+
github_token: ${{ secrets.GITHUB_TOKEN }}
124+
branch: gh-pages
73125
build-n-publish:
74126
name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
75127
runs-on: ubuntu-latest
@@ -78,7 +130,7 @@ jobs:
78130
permissions:
79131
# IMPORTANT: this permission is mandatory for trusted publishing
80132
id-token: write
81-
needs: [tests, generate]
133+
needs: [tests, json_schemas, docs]
82134
steps:
83135
- uses: actions/checkout@v4
84136
- name: Set up Python

‎.github/workflows/test_docs.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: "Test Doc Creation (Sphinx)"
2+
on: [pull_request]
3+
jobs:
4+
docbuild:
5+
name: Check Docs
6+
runs-on: ${{ matrix.os }}
7+
strategy:
8+
matrix:
9+
python-version: ["3.12"]
10+
os: [ubuntu-latest]
11+
steps:
12+
- uses: actions/checkout@v4
13+
- name: Set up Python ${{ matrix.python-version }}
14+
uses: actions/setup-python@v5
15+
with:
16+
python-version: ${{ matrix.python-version }}
17+
- name: Install dependencies
18+
run: |
19+
python -m pip install --upgrade pip
20+
pip install tox
21+
- name: Check Docs
22+
run: |
23+
tox -e docs

‎.readthedocs.yaml‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎docs/conf.py‎

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -97,15 +97,6 @@
9797
project = "bo4e"
9898
copyright = "2022, Hochfrequenz GmbH"
9999

100-
# The version info for the project you're documenting, acts as replacement for
101-
# |version| and |release|, also used in various other places throughout the
102-
# built documents.
103-
#
104-
# The short X.Y version.
105-
version = "" # Is set by calling `setup.py docs`
106-
# The full version, including alpha/beta/rc tags.
107-
release = "" # Is set by calling `setup.py docs`
108-
109100
# The language for content autogenerated by Sphinx. Refer to documentation
110101
# for a list of supported languages.
111102
# language = None
@@ -176,8 +167,12 @@
176167

177168
# The name for this set of Sphinx documents. If None, it defaults to
178169
# "<project> v<release> documentation".
179-
from bo4e import __gh_version__ as release
180-
from bo4e import __version__ as version
170+
# Note: For the deployment to GitHub Pages the release and version values will
171+
# be set by the action. This is to support things like /latest or /stable.
172+
if "release" not in globals():
173+
from bo4e import __gh_version__ as release
174+
if "version" not in globals():
175+
from bo4e import __version__ as version
181176

182177
print(f"Got version = {version} from __version__")
183178
print(f"Got release = {release} from __gh_version__")
@@ -309,7 +304,7 @@
309304

310305
# Create UML diagrams in plantuml format. Compile these into svg files into the _static folder.
311306
# See docs/uml.py for more details.
312-
uml.LINK_URI_BASE = f"https://bo4e-python.readthedocs.io/en/{release}"
307+
uml.LINK_URI_BASE = f"https://bo4e.github.io/BO4E-python/{release}"
313308
_exec_plantuml = Path(__location__) / "plantuml.jar"
314309
_network, _namespaces_to_parse = uml.build_network(Path(module_dir), uml.PlantUMLNetwork)
315310
print(_network)

‎docs/uml.py‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -79,11 +79,8 @@ def __init__(self, *, scope: Optional[List[str]] = None, color: Optional[str] =
7979
#: Define shorthand for Cardinality type since none of the values have to be provided.
8080
Cardinality = tuple[str, str]
8181

82-
#: Define the link base URI used in svg links
83-
LINK_URI_BASE = "https://bo4e-python.readthedocs.io/en/latest"
84-
85-
# link domain to test links only local.
86-
# LINK_URI_BASE = f"file:///{Path.cwd().parent}/.tox/docs/tmp/html"
82+
#: Define the link base URI used in svg links. Will be overridden by conf.py.
83+
LINK_URI_BASE = f"file:///{Path(__file__).parents[1]}/.tox/docs/tmp/html"
8784

8885

8986
class _UMLNetworkABC(nx.MultiDiGraph, metaclass=ABCMeta):

0 commit comments

Comments
 (0)