Skip to content
This repository was archived by the owner on Sep 9, 2026. It is now read-only.

Commit 2711aef

Browse files
Jackmin801Jackmin801
authored
docs: add versioned documentation (#664)
1 parent bfdccf5 commit 2711aef

7 files changed

Lines changed: 252 additions & 49 deletions

File tree

‎.github/workflows/build-old-docs.yml‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
name: Build old docs
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
release_token:
7+
description: 'Your release token'
8+
required: true
9+
triggered_by:
10+
description: 'CD | TAG | MANUAL'
11+
required: false
12+
default: MANUAL
13+
package:
14+
description: The name of the repo to build documentation for.
15+
type: string
16+
default: docarray
17+
repo_owner:
18+
description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
19+
type: string
20+
default: jina-ai
21+
pages_branch:
22+
description: Branch that Github Pages observes
23+
type: string
24+
default: gh-pages
25+
git_config_name:
26+
type: string
27+
default: Jina Dev Bot
28+
git_config_email:
29+
type: string
30+
default: [email protected]
31+
32+
jobs:
33+
token-check:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- run: echo "Success!"
37+
if: "${{ github.event.inputs.release_token }} == ${{ env.release_token }}"
38+
env:
39+
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}
40+
- id: get_versions
41+
run: |
42+
printf "versions=" >> $GITHUB_OUTPUT
43+
curl https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_versions.json >> $GITHUB_OUTPUT
44+
outputs:
45+
versions: ${{ steps.get_versions.outputs.versions }}
46+
47+
build-doc:
48+
needs: token-check
49+
runs-on: ubuntu-latest
50+
strategy:
51+
fail-fast: false
52+
matrix:
53+
include: ${{ fromJson(needs.token-check.outputs.versions) }}
54+
steps:
55+
- uses: actions/checkout@v3
56+
with:
57+
fetch-depth: 1
58+
ref: ${{ matrix.version }}
59+
- uses: actions/setup-python@v4
60+
with:
61+
python-version: '3.7'
62+
- name: Get latest templates
63+
run: |
64+
git show --summary
65+
echo "Get latest sidebar brand template"
66+
wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_templates/sidebar/brand.html
67+
mv ./brand.html ./docs/_templates/sidebar/brand.html
68+
- name: Install dependencies
69+
run: |
70+
python -m pip install --upgrade pip
71+
python -m pip install wheel
72+
# pip does not properly resolve dependency versions with syntax pip install --no-cache-dir ".[test,full]"
73+
pip install --no-cache-dir ".[test]"
74+
pip install --no-cache-dir ".[full]"
75+
pip install --no-cache-dir ".[qdrant]"
76+
pip install --no-cache-dir ".[annlite]"
77+
pip install --no-cache-dir ".[weaviate]"
78+
pip install --no-cache-dir ".[elasticsearch]"
79+
pip install --no-cache-dir ".[redis]"
80+
cd docs
81+
pip install -r requirements.txt
82+
pip install --pre -U furo
83+
pip install sphinx-markdown-tables==0.0.17
84+
- name: Sphinx Build
85+
run: |
86+
cd docs
87+
bash makedoc.sh
88+
- name: Package build into artifact
89+
run: |
90+
mv ./docs/_build/dirhtml ./${{ matrix.version }}
91+
zip -r /tmp/build.zip ./${{ matrix.version }}/*
92+
- name: Upload built html
93+
uses: actions/upload-artifact@v3
94+
with:
95+
name: ${{ matrix.version }}
96+
path: /tmp/build.zip
97+
retention-days: 1
98+
99+
push-docs:
100+
runs-on: ubuntu-latest
101+
needs: build-doc
102+
steps:
103+
- uses: actions/checkout@v3
104+
with:
105+
fetch-depth: 1
106+
ref: ${{ inputs.pages_branch }}
107+
- uses: actions/download-artifact@v3
108+
with:
109+
path: /tmp/artifacts
110+
- name: Clear old builds
111+
run: |
112+
cd docs
113+
for i in $(ls /tmp/artifacts); do git rm -rf "$i" || true; done
114+
- name: In with new builds
115+
run: |
116+
cd docs
117+
for i in $(ls /tmp/artifacts); do unzip "/tmp/artifacts/$i/build.zip"; done
118+
rm _versions.json
119+
wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_versions.json
120+
- name: Push it up!
121+
run: |
122+
git config --local user.email "${{ inputs.git_config_email }}"
123+
git config --local user.name "${{ inputs.git_config_name }}"
124+
git show --summary
125+
git add . && git commit -m "chore(docs): update old docs due to ${{github.event_name}} on ${{github.repository}}"
126+
git push origin

‎.github/workflows/force-docs-build.yml‎

Lines changed: 72 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,28 @@ on:
1010
description: 'CD | TAG | MANUAL'
1111
required: false
1212
default: MANUAL
13+
build_old_docs:
14+
description: 'Whether to build old docs (TRUE | FALSE)'
15+
type: string
16+
default: 'FALSE'
17+
package:
18+
description: The name of the repo to build documentation for.
19+
type: string
20+
default: docarray
21+
repo_owner:
22+
description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
23+
type: string
24+
default: jina-ai
25+
pages_branch:
26+
description: Branch that Github Pages observes
27+
type: string
28+
default: gh-pages
29+
git_config_name:
30+
type: string
31+
default: Jina Dev Bot
32+
git_config_email:
33+
type: string
34+
default: [email protected]
1335

1436
jobs:
1537
token-check:
@@ -20,20 +42,18 @@ jobs:
2042
env:
2143
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}
2244

23-
release-docs:
45+
build-and-push-latest-docs:
2446
needs: token-check
2547
runs-on: ubuntu-latest
2648
steps:
27-
- uses: actions/checkout@v2.5.0
49+
- uses: actions/checkout@v3
2850
with:
29-
fetch-depth: 0
51+
fetch-depth: 1
3052
- uses: actions/setup-python@v4
3153
with:
32-
python-version: 3.7
33-
- name: Build doc and push to gh-pages
54+
python-version: '3.7'
55+
- name: Install Dependencies
3456
run: |
35-
git config --local user.email "[email protected]"
36-
git config --local user.name "Jina Dev Bot"
3757
python -m pip install --upgrade pip
3858
python -m pip install wheel
3959
# pip does not properly resolve dependency versions with syntax pip install --no-cache-dir ".[test,full]"
@@ -44,28 +64,52 @@ jobs:
4464
pip install --no-cache-dir ".[weaviate]"
4565
pip install --no-cache-dir ".[elasticsearch]"
4666
pip install --no-cache-dir ".[redis]"
47-
mkdir gen-html
4867
cd docs
4968
pip install -r requirements.txt
5069
pip install --pre -U furo
70+
pip install sphinx-markdown-tables==0.0.17
71+
- name: Sphinx Build
72+
run: |
73+
cd docs
5174
bash makedoc.sh
52-
cd ./_build/dirhtml/
53-
cp -r ./ ../../../gen-html
54-
cd - # back to ./docs
55-
cd ..
56-
git checkout -f gh-pages
57-
git rm -rf ./docs
58-
mkdir -p docs
59-
cd gen-html
60-
cp -r ./ ../docs
61-
cd ../docs
62-
ls -la
63-
touch .nojekyll
64-
cp 404/index.html 404.html
65-
sed -i 's/href="\.\./href="/' 404.html # fix asset urls that needs to be updated in 404.html
66-
echo docarray.jina.ai > CNAME
67-
cd ..
68-
git add docs
69-
git status
70-
git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
71-
git push --force origin gh-pages
75+
mv ./_build/dirhtml /tmp/gen-html
76+
- name: Checkout to GH pages branch (${{ inputs.pages_branch }})
77+
run: |
78+
git fetch origin ${{ inputs.pages_branch }}:${{ inputs.pages_branch }} --depth 1
79+
git checkout -f ${{ inputs.pages_branch }}
80+
git reset --hard HEAD
81+
- name: Small config stuff
82+
run: |
83+
touch /tmp/gen-html/.nojekyll
84+
cp ./docs/CNAME /tmp/gen-html/CNAME
85+
cp ./docs/_versions.json /tmp/gen-html/_versions.json
86+
cp /tmp/gen-html/404/index.html /tmp/gen-html/404.html
87+
sed -i 's/href="\.\./href="/' /tmp/gen-html/404.html # fix asset urls that needs to be updated in 404.html
88+
- name: Moving old doc versions
89+
run: |
90+
cd docs
91+
for i in $(cat _versions.json | jq '.[].version' | tr -d '"'); do mv "$i" /tmp/gen-html; done
92+
- name: Swap in new docs
93+
run: |
94+
rm -rf ./docs
95+
mv /tmp/gen-html ./docs
96+
- name: Push it up!
97+
run: |
98+
git config --local user.email "${{ inputs.git_config_email }}"
99+
git config --local user.name "${{ inputs.git_config_name }}"
100+
git show --summary
101+
git add ./docs && git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
102+
git push origin ${{ inputs.pages_branch }}
103+
104+
build-old-docs:
105+
needs: build-and-push-latest-docs
106+
runs-on: ubuntu-latest
107+
if: inputs.build_old_docs == 'TRUE'
108+
steps:
109+
- uses: benc-uk/workflow-dispatch@v1
110+
with:
111+
workflow: Build old docs
112+
token: ${{ secrets.JINA_DEV_BOT }}
113+
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
114+
env:
115+
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}

‎.github/workflows/tag.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ jobs:
1818
with:
1919
workflow: Manual Docs Build
2020
token: ${{ secrets.JINA_DEV_BOT }}
21-
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
21+
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG", "build_old_docs": "TRUE"}'
2222
env:
2323
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}
2424

‎docs/_templates/sidebar/brand.html‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -16,26 +16,33 @@
1616
{%- endif %}
1717
{% endblock brand_content %}
1818
</a>
19+
<script>
20+
function setPrefix(prefix){
21+
window.sessionStorage.setItem("version-select-index", document.getElementsByClassName("version-select")[0].selectedIndex);
22+
window.location.href = prefix
23+
}
24+
</script>
25+
<script defer>
26+
fetch(`https://${window.location.host}/_versions.json`)
27+
.then((resp) => resp.json())
28+
.then((data) => {
29+
var versionSelector = document.getElementsByClassName("version-select")[0]
30+
for(var i = 0; i < data.length; i++){
31+
var option = document.createElement("option");
32+
option.innerHTML = data[i].version;
33+
option.value = "/" + data[i].version;
34+
versionSelector.appendChild(option);
35+
}
36+
37+
if(window.sessionStorage.getItem('version-select-index')){
38+
versionSelector.selectedIndex = window.sessionStorage.getItem('version-select-index');
39+
}
40+
})
41+
.catch((err) => console.log(err));
42+
</script>
1943
<div class="sd-d-flex-row sd-align-major-spaced">
2044
<a class="github-button" href="https://github.com/jina-ai/docarray" data-icon="octicon-star" data-show-count="true" aria-label="Star jina-ai/jina on GitHub" style="opacity: 0;">Star</a>
21-
{% if versions %}
22-
<select onChange="window.location.href=this.value" class="version-select">
23-
{%- for item in versions|reverse %}
24-
{% if item.name == latest_jina_version %}
25-
{% set new_url = item.url if current_version.name == latest_jina_version else item.url | replace('/' + latest_jina_version, "") %}
26-
{% if current_version.version == item.version %}
27-
<option value="{{ new_url }}" selected="selected" >latest ({{ item.name }})</option>
28-
{% else %}
29-
<option value="{{ new_url }}" >latest({{ item.name }})</option>
30-
{% endif %}
31-
{% else %}
32-
{% if current_version.version == item.version %}
33-
<option value="{{ item.url }}" selected="selected" >{{ item.name }}</option>
34-
{% else %}
35-
<option value="{{ item.url }}" >{{ item.name }}</option>
36-
{% endif %}
37-
{% endif %}
38-
{%- endfor %}
45+
<select onChange="setPrefix(this.value)" class="version-select">
46+
<option value="/">latest</option>
3947
</select>
40-
{% endif %}
41-
</div>
48+
</div>

‎docs/_versions.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
[{"version": "v0.18.1"}, {"version": "v0.18.0"}, {"version": "v0.17.0"}, {"version": "v0.16.5"}, {"version": "v0.16.0"}, {"version": "v0.15.4"}, {"version": "v0.15.0"}, {"version": "v0.14.11"}, {"version": "v0.14.0"}, {"version": "v0.13.33"}, {"version": "v0.13.0"}, {"version": "v0.12.9"}, {"version": "v0.12.0"}, {"version": "v0.11.3"}, {"version": "v0.11.0"}, {"version": "v0.10.5"}, {"version": "v0.10.0"}, {"version": "v0.9.18"}, {"version": "v0.9.0"}, {"version": "v0.8.11"}, {"version": "v0.8.0"}, {"version": "v0.7.3"}, {"version": "v0.7.0"}, {"version": "v0.6.3"}, {"version": "v0.6.0"}, {"version": "v0.5.3"}, {"version": "v0.5.0"}, {"version": "v0.4.3"}, {"version": "v0.4.0"}, {"version": "v0.3.3"}, {"version": "v0.3.0"}, {"version": "v0.2.0"}, {"version": "v0.1.7"}, {"version": "v0.1.1"}, {"version": "v0.0.0"}]

‎scripts/prepend_version_json.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
from typing import List
2+
import argparse
3+
import json
4+
5+
parser = argparse.ArgumentParser(prog="Prepender docs/_versions.json")
6+
parser.add_argument(
7+
"--version",
8+
type=str,
9+
help="The version we wish to prepend (e.g. v0.18.0)",
10+
required=True,
11+
)
12+
args = parser.parse_args()
13+
14+
with open("./docs/_versions.json") as f:
15+
versions: List[dict] = json.load(f)
16+
element = {k: v for k, v in args._get_kwargs()}
17+
if element != versions[0]:
18+
versions.insert(0, element)
19+
20+
with open("./docs/_versions.json", "w") as f:
21+
json.dump(versions, f)

‎scripts/release.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,10 @@ export RELEASE_VER=$(sed -n '/^__version__/p' $INIT_FILE | cut -d \' -f2)
7272
LAST_VER=$(git tag -l | sort -V | tail -n1)
7373
printf "last version: \e[1;32m$LAST_VER\e[0m\n"
7474

75+
# Update new _versions.json if necessary
76+
python ./scripts/prepend_version_json.py --version "v$RELEASE_VER"
77+
git add ./docs/_versions.json
78+
7579
if [[ $1 == "final" ]]; then
7680
printf "this will be a final release: \e[1;33m$RELEASE_VER\e[0m\n"
7781

0 commit comments

Comments
 (0)