Skip to content

docs: add versioned documentation #664

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
JoanFM merged 16 commits into from
Oct 25, 2022
Merged

docs: add versioned documentation #664

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
474d414
docs: add versioned docs to sidebar
Jackmin801 Oct 23, 2022
d24e82b
docs: add version metadata
Jackmin801 Oct 20, 2022
2234dbe
ci: add workflow to build old docs
Jackmin801 Oct 23, 2022
9745555
ci: version aware build workflow for latest docs
Jackmin801 Oct 23, 2022
df156a7
style: blacken doc scripts
Jackmin801 Oct 23, 2022
8d825d1
ci: revert python version to 3.7 in docs workflows
Jackmin801 Oct 24, 2022
25c75ef
ci: revert installs to previous method
Jackmin801 Oct 24, 2022
940e42c
ci: fix typos
Jackmin801 Oct 24, 2022
401ccf8
ci: update _versions.json when manual release
Jackmin801 Oct 24, 2022
5204640
ci: add build_old_docs flag to manual docs build
Jackmin801 Oct 24, 2022
be5cf76
ci: add better description for old docs flag
Jackmin801 Oct 24, 2022
7af58e4
ci: release CD builds old docs after a latest
Jackmin801 Oct 24, 2022
207f38b
ci: remove old _versions.json correctly
Jackmin801 Oct 24, 2022
a8649fe
ci: revert blacken in docs/conf.py
Jackmin801 Oct 25, 2022
990b0ca
ci: consolidate doc version information to json
Jackmin801 Oct 25, 2022
d695c90
docs: add new release to _versions.json
Jackmin801 Oct 25, 2022
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
126 changes: 126 additions & 0 deletions .github/workflows/build-old-docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
name: Build old docs

on:
workflow_dispatch:
inputs:
release_token:
description: 'Your release token'
required: true
triggered_by:
description: 'CD | TAG | MANUAL'
required: false
default: MANUAL
package:
description: The name of the repo to build documentation for.
type: string
default: docarray
repo_owner:
description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
type: string
default: jina-ai
pages_branch:
description: Branch that Github Pages observes
type: string
default: gh-pages
git_config_name:
type: string
default: Jina Dev Bot
git_config_email:
type: string
default: [email protected]

jobs:
token-check:
runs-on: ubuntu-latest
steps:
- run: echo "Success!"
if: "${{ github.event.inputs.release_token }} == ${{ env.release_token }}"
env:
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}
- id: get_versions
run: |
printf "versions=" >> $GITHUB_OUTPUT
curl https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_versions.json >> $GITHUB_OUTPUT
outputs:
versions: ${{ steps.get_versions.outputs.versions }}

build-doc:
needs: token-check
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
include: ${{ fromJson(needs.token-check.outputs.versions) }}
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 1
ref: ${{ matrix.version }}
- uses: actions/setup-python@v4
with:
python-version: '3.7'
- name: Get latest templates
run: |
git show --summary
echo "Get latest sidebar brand template"
wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_templates/sidebar/brand.html
mv ./brand.html ./docs/_templates/sidebar/brand.html
- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install wheel
# pip does not properly resolve dependency versions with syntax pip install --no-cache-dir ".[test,full]"
pip install --no-cache-dir ".[test]"
pip install --no-cache-dir ".[full]"
pip install --no-cache-dir ".[qdrant]"
pip install --no-cache-dir ".[annlite]"
pip install --no-cache-dir ".[weaviate]"
pip install --no-cache-dir ".[elasticsearch]"
pip install --no-cache-dir ".[redis]"
cd docs
pip install -r requirements.txt
pip install --pre -U furo
pip install sphinx-markdown-tables==0.0.17
- name: Sphinx Build
run: |
cd docs
bash makedoc.sh
- name: Package build into artifact
run: |
mv ./docs/_build/dirhtml ./${{ matrix.version }}
zip -r /tmp/build.zip ./${{ matrix.version }}/*
- name: Upload built html
uses: actions/upload-artifact@v3
with:
name: ${{ matrix.version }}
path: /tmp/build.zip
retention-days: 1

push-docs:
runs-on: ubuntu-latest
needs: build-doc
steps:
- uses: actions/checkout@v3
with:
fetch-depth: 1
ref: ${{ inputs.pages_branch }}
- uses: actions/download-artifact@v3
with:
path: /tmp/artifacts
- name: Clear old builds
run: |
cd docs
for i in $(ls /tmp/artifacts); do git rm -rf "$i" || true; done
- name: In with new builds
run: |
cd docs
for i in $(ls /tmp/artifacts); do unzip "/tmp/artifacts/$i/build.zip"; done
rm _versions.json
wget https://raw.githubusercontent.com/${{ inputs.repo_owner }}/${{ inputs.package }}/main/docs/_versions.json
- name: Push it up!
run: |
git config --local user.email "${{ inputs.git_config_email }}"
git config --local user.name "${{ inputs.git_config_name }}"
git show --summary
git add . && git commit -m "chore(docs): update old docs due to ${{github.event_name}} on ${{github.repository}}"
git push origin
100 changes: 72 additions & 28 deletions .github/workflows/force-docs-build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,28 @@ on:
description: 'CD | TAG | MANUAL'
required: false
default: MANUAL
build_old_docs:
description: 'Whether to build old docs (TRUE | FALSE)'
type: string
default: 'FALSE'
package:
description: The name of the repo to build documentation for.
type: string
default: docarray
repo_owner:
description: The owner of the repo to build documentation for. Defaults to 'jina-ai'.
type: string
default: jina-ai
pages_branch:
description: Branch that Github Pages observes
type: string
default: gh-pages
git_config_name:
type: string
default: Jina Dev Bot
git_config_email:
type: string
default: [email protected]

jobs:
token-check:
Expand All @@ -20,20 +42,18 @@ jobs:
env:
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}

release-docs:
build-and-push-latest-docs:
needs: token-check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2.5.0
- uses: actions/checkout@v3
with:
fetch-depth: 0
fetch-depth: 1
- uses: actions/setup-python@v4
with:
python-version: 3.7
- name: Build doc and push to gh-pages
python-version: '3.7'
- name: Install Dependencies
run: |
git config --local user.email "[email protected]"
git config --local user.name "Jina Dev Bot"
python -m pip install --upgrade pip
python -m pip install wheel
# pip does not properly resolve dependency versions with syntax pip install --no-cache-dir ".[test,full]"
Expand All @@ -44,28 +64,52 @@ jobs:
pip install --no-cache-dir ".[weaviate]"
pip install --no-cache-dir ".[elasticsearch]"
pip install --no-cache-dir ".[redis]"
mkdir gen-html
cd docs
pip install -r requirements.txt
pip install --pre -U furo
pip install sphinx-markdown-tables==0.0.17
- name: Sphinx Build
run: |
cd docs
bash makedoc.sh
cd ./_build/dirhtml/
cp -r ./ ../../../gen-html
cd - # back to ./docs
cd ..
git checkout -f gh-pages
git rm -rf ./docs
mkdir -p docs
cd gen-html
cp -r ./ ../docs
cd ../docs
ls -la
touch .nojekyll
cp 404/index.html 404.html
sed -i 's/href="\.\./href="/' 404.html # fix asset urls that needs to be updated in 404.html
echo docarray.jina.ai > CNAME
cd ..
git add docs
git status
git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
git push --force origin gh-pages
mv ./_build/dirhtml /tmp/gen-html
- name: Checkout to GH pages branch (${{ inputs.pages_branch }})
run: |
git fetch origin ${{ inputs.pages_branch }}:${{ inputs.pages_branch }} --depth 1
git checkout -f ${{ inputs.pages_branch }}
git reset --hard HEAD
- name: Small config stuff
run: |
touch /tmp/gen-html/.nojekyll
cp ./docs/CNAME /tmp/gen-html/CNAME
cp ./docs/_versions.json /tmp/gen-html/_versions.json
cp /tmp/gen-html/404/index.html /tmp/gen-html/404.html
sed -i 's/href="\.\./href="/' /tmp/gen-html/404.html # fix asset urls that needs to be updated in 404.html
- name: Moving old doc versions
run: |
cd docs
for i in $(cat _versions.json | jq '.[].version' | tr -d '"'); do mv "$i" /tmp/gen-html; done
- name: Swap in new docs
run: |
rm -rf ./docs
mv /tmp/gen-html ./docs
- name: Push it up!
run: |
git config --local user.email "${{ inputs.git_config_email }}"
git config --local user.name "${{ inputs.git_config_name }}"
git show --summary
git add ./docs && git commit -m "chore(docs): update docs due to ${{github.event_name}} on ${{github.repository}}"
git push origin ${{ inputs.pages_branch }}

build-old-docs:
needs: build-and-push-latest-docs
runs-on: ubuntu-latest
if: inputs.build_old_docs == 'TRUE'
steps:
- uses: benc-uk/workflow-dispatch@v1
with:
workflow: Build old docs
token: ${{ secrets.JINA_DEV_BOT }}
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
env:
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}
2 changes: 1 addition & 1 deletion .github/workflows/tag.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ jobs:
with:
workflow: Manual Docs Build
token: ${{ secrets.JINA_DEV_BOT }}
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG"}'
inputs: '{ "release_token": "${{ env.release_token }}", "triggered_by": "TAG", "build_old_docs": "TRUE"}'
env:
release_token: ${{ secrets.DOCARRAY_RELEASE_TOKEN }}

Expand Down
47 changes: 27 additions & 20 deletions docs/_templates/sidebar/brand.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,26 +16,33 @@
{%- endif %}
{% endblock brand_content %}
</a>
<script>
function setPrefix(prefix){
window.sessionStorage.setItem("version-select-index", document.getElementsByClassName("version-select")[0].selectedIndex);
window.location.href = prefix
}
</script>
<script defer>
fetch(`https://${window.location.host}/_versions.json`)
.then((resp) => resp.json())
.then((data) => {
var versionSelector = document.getElementsByClassName("version-select")[0]
for(var i = 0; i < data.length; i++){
var option = document.createElement("option");
option.innerHTML = data[i].version;
option.value = "/" + data[i].version;
versionSelector.appendChild(option);
}

if(window.sessionStorage.getItem('version-select-index')){
versionSelector.selectedIndex = window.sessionStorage.getItem('version-select-index');
}
})
.catch((err) => console.log(err));
</script>
<div class="sd-d-flex-row sd-align-major-spaced">
<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>
{% if versions %}
<select onChange="window.location.href=this.value" class="version-select">
{%- for item in versions|reverse %}
{% if item.name == latest_jina_version %}
{% set new_url = item.url if current_version.name == latest_jina_version else item.url | replace('/' + latest_jina_version, "") %}
{% if current_version.version == item.version %}
<option value="{{ new_url }}" selected="selected" >latest ({{ item.name }})</option>
{% else %}
<option value="{{ new_url }}" >latest({{ item.name }})</option>
{% endif %}
{% else %}
{% if current_version.version == item.version %}
<option value="{{ item.url }}" selected="selected" >{{ item.name }}</option>
{% else %}
<option value="{{ item.url }}" >{{ item.name }}</option>
{% endif %}
{% endif %}
{%- endfor %}
<select onChange="setPrefix(this.value)" class="version-select">
<option value="/">latest</option>
</select>
{% endif %}
</div>
</div>
1 change: 1 addition & 0 deletions docs/_versions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +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"}]
21 changes: 21 additions & 0 deletions scripts/prepend_version_json.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
from typing import List
import argparse
import json

parser = argparse.ArgumentParser(prog="Prepender docs/_versions.json")
parser.add_argument(
"--version",
type=str,
help="The version we wish to prepend (e.g. v0.18.0)",
required=True,
)
args = parser.parse_args()

with open("./docs/_versions.json") as f:
versions: List[dict] = json.load(f)
element = {k: v for k, v in args._get_kwargs()}
if element != versions[0]:
versions.insert(0, element)

with open("./docs/_versions.json", "w") as f:
json.dump(versions, f)
4 changes: 4 additions & 0 deletions scripts/release.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,10 @@ export RELEASE_VER=$(sed -n '/^__version__/p' $INIT_FILE | cut -d \' -f2)
LAST_VER=$(git tag -l | sort -V | tail -n1)
printf "last version: \e[1;32m$LAST_VER\e[0m\n"

# Update new _versions.json if necessary
python ./scripts/prepend_version_json.py --version "v$RELEASE_VER"
git add ./docs/_versions.json

if [[ $1 == "final" ]]; then
printf "this will be a final release: \e[1;33m$RELEASE_VER\e[0m\n"

Expand Down