Skip to content

Commit 8b3cc5e

Browse files
kheiss-uwzookheiss-uwzoo
authored
ci(docs): automate docs.nvidia.com publish and enable public docs features (#2223)
1 parent 05d6914 commit 8b3cc5e

6 files changed

Lines changed: 305 additions & 58 deletions

File tree

‎.github/workflows/nrl-docs-nvidia-publish.yml‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# NeMo Retriever Library (NRL) — publish MkDocs site to docs.nvidia.com (S3 + Akamai).
2+
#
3+
# Replaces the manual brightspot S3 upload and Akamai ECCU flush for NRL guide content.
4+
# MkDocs-only (no Sphinx / mike deploy). GitHub Pages remains nrl-docs-github-pages.yml.
5+
#
6+
# Required GitHub configuration (NVIDIA/NeMo-Retriever org/repo):
7+
# Environment: docs-nvidia-prod (recommended approval gate before first live publish)
8+
# Secrets: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ASSUME_ROLE_ARN,
9+
# S3_BUCKET_NAME, AKAMAI_HOST, AKAMAI_CLIENT_TOKEN, AKAMAI_CLIENT_SECRET,
10+
# AKAMAI_ACCESS_TOKEN
11+
# Variables (optional): DOCS_AWS_REGION, NRL_DOCS_PUBLISH_VERSION, DOCS_RELEASE_EMAILS
12+
#
13+
# S3 layout written under developer/docs/nemo/retriever/:
14+
# index.html, versions.json, latest/, <version>/ (e.g. 26.5.0/)
15+
#
16+
# Per-release operator steps (before merge or tag):
17+
# 1. Edit docs/publish/versions.json — add the new version, move the "latest" alias,
18+
# keep older entries unless retiring them.
19+
# 2. Set NRL_DOCS_PUBLISH_VERSION to the release version, or push a version tag
20+
# (e.g. v26.5.0 or release-v26.5.0) so publish-docs and SITE_URL stay aligned.
21+
# 3. Merge doc changes to main (or push the tag). CI copies versions.json into the
22+
# artifact, builds with SITE_URL=.../retriever/<version>/, and runs publish-docs.
23+
# Backports to old branches: workflow_dispatch with publish-as-latest: false (or /not-latest
24+
# in the commit message); do not move the "latest" alias in versions.json.
25+
name: NRL documentation — docs.nvidia.com publish
26+
27+
on:
28+
push:
29+
branches:
30+
- main
31+
tags:
32+
- "v[0-9]*.[0-9]*"
33+
- "*-v[0-9]*.[0-9]*"
34+
paths:
35+
- "docs/**"
36+
- "nemo_retriever/**"
37+
- ".github/workflows/nrl-docs-nvidia-publish.yml"
38+
workflow_dispatch:
39+
inputs:
40+
dry-run:
41+
description: Skip S3 sync and Akamai flush (download/build only)
42+
required: true
43+
type: boolean
44+
default: true
45+
docs-version-override:
46+
description: Version folder to publish (e.g. 26.5.0). Empty uses tag, NRL_DOCS_PUBLISH_VERSION, or 26.5.0.
47+
required: false
48+
type: string
49+
default: ""
50+
publish-as-latest:
51+
description: Also sync the same build to latest/ (set false for backports)
52+
required: false
53+
type: boolean
54+
default: true
55+
notify-emails:
56+
description: Extra Akamai notification emails (comma-separated)
57+
required: false
58+
type: string
59+
default: ""
60+
61+
permissions:
62+
contents: read
63+
64+
concurrency:
65+
group: nrl-docs-nvidia-publish
66+
cancel-in-progress: false
67+
68+
env:
69+
# Immutable pin for publish-docs (release v0.80.2). Do not use the mutable v0.80.2 tag.
70+
FW_CI_TEMPLATES_REF: 563a769458cf1428194be49cb4de575b72d739e8
71+
DOCS_SITE_URL_BASE: https://docs.nvidia.com/nemo/retriever
72+
S3_TARGET_PATH: developer/docs/nemo/retriever
73+
ARTIFACT_NAME: nrl-docs-nvidia-site
74+
75+
jobs:
76+
resolve:
77+
name: Resolve publish version and flags
78+
runs-on: ubuntu-latest
79+
outputs:
80+
docs_version: ${{ steps.publish.outputs.docs_version }}
81+
dry_run: ${{ steps.publish.outputs.dry_run }}
82+
publish_latest: ${{ steps.publish.outputs.publish_latest }}
83+
emails_csv: ${{ steps.publish.outputs.emails_csv }}
84+
site_url: ${{ steps.publish.outputs.site_url }}
85+
steps:
86+
- name: Resolve publish inputs
87+
id: publish
88+
env:
89+
DISPATCH_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry-run }}
90+
VERSION_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.docs-version-override || '' }}
91+
PUBLISH_LATEST_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.publish-as-latest }}
92+
NOTIFY_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.notify-emails || '' }}
93+
NRL_DOCS_PUBLISH_VERSION_VAR: ${{ vars.NRL_DOCS_PUBLISH_VERSION }}
94+
DOCS_RELEASE_EMAILS_VAR: ${{ vars.DOCS_RELEASE_EMAILS }}
95+
HEAD_COMMIT_MSG: ${{ github.event.head_commit.message || '' }}
96+
GITHUB_REF_NAME: ${{ github.ref }}
97+
run: |
98+
if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
99+
echo "dry_run=${DISPATCH_DRY_RUN}" >> "$GITHUB_OUTPUT"
100+
echo "publish_latest=${PUBLISH_LATEST_INPUT}" >> "$GITHUB_OUTPUT"
101+
else
102+
echo "dry_run=false" >> "$GITHUB_OUTPUT"
103+
echo "publish_latest=true" >> "$GITHUB_OUTPUT"
104+
fi
105+
106+
VERSION="${VERSION_INPUT}"
107+
if [[ -z "${VERSION}" ]]; then
108+
if [[ "${GITHUB_REF_NAME}" =~ -v([0-9]+\.[0-9]+(\.[0-9]+)?)$ ]]; then
109+
VERSION="${BASH_REMATCH[1]}"
110+
elif [[ "${GITHUB_REF_NAME}" =~ ^refs/tags/v([0-9]+\.[0-9]+(\.[0-9]+)?)$ ]]; then
111+
VERSION="${BASH_REMATCH[1]}"
112+
fi
113+
fi
114+
if [[ -z "${VERSION}" ]]; then
115+
VERSION="${NRL_DOCS_PUBLISH_VERSION_VAR}"
116+
fi
117+
if [[ -z "${VERSION}" ]]; then
118+
VERSION="26.5.0"
119+
fi
120+
echo "docs_version=${VERSION}" >> "$GITHUB_OUTPUT"
121+
echo "site_url=${{ env.DOCS_SITE_URL_BASE }}/${VERSION}/" >> "$GITHUB_OUTPUT"
122+
123+
if [[ "${{ github.event_name }}" != "workflow_dispatch" ]]; then
124+
if [[ "${HEAD_COMMIT_MSG}" =~ /not-latest ]] || [[ "${GITHUB_REF_NAME}" =~ not-latest ]]; then
125+
echo "publish_latest=false" >> "$GITHUB_OUTPUT"
126+
fi
127+
fi
128+
129+
EMAILS="${DOCS_RELEASE_EMAILS_VAR}"
130+
if [[ -n "${NOTIFY_INPUT}" ]]; then
131+
if [[ -n "${EMAILS}" ]]; then
132+
EMAILS="${EMAILS},${NOTIFY_INPUT}"
133+
else
134+
EMAILS="${NOTIFY_INPUT}"
135+
fi
136+
fi
137+
echo "emails_csv=${EMAILS}" >> "$GITHUB_OUTPUT"
138+
139+
build:
140+
name: Build NRL docs for docs.nvidia.com
141+
needs: resolve
142+
runs-on: ubuntu-latest
143+
steps:
144+
- name: Checkout
145+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
146+
147+
- name: Set up Python
148+
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
149+
with:
150+
python-version: "3.12"
151+
cache: pip
152+
cache-dependency-path: docs/requirements.txt
153+
154+
- name: Install Python dependencies
155+
run: |
156+
python -m pip install --upgrade pip
157+
pip install -r docs/requirements.txt
158+
pip install -e ./nemo_retriever
159+
160+
- name: Build MkDocs (production site_url)
161+
working-directory: docs
162+
env:
163+
SITE_URL: ${{ needs.resolve.outputs.site_url }}
164+
DISABLE_MKDOCS_2_WARNING: "true"
165+
run: mkdocs build -f mkdocs.yml --strict
166+
167+
# MkDocs does not emit versions.json. publish-docs uploads the artifact copy to S3
168+
# (it does not merge with the live S3 file). docs/publish/versions.json is canonical.
169+
- name: Stage version picker metadata for publish-docs
170+
run: |
171+
cp docs/publish/versions.json docs/site/versions.json
172+
173+
- name: Upload docs.nvidia.com site artifact
174+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
175+
with:
176+
name: ${{ env.ARTIFACT_NAME }}
177+
path: docs/site
178+
if-no-files-found: error
179+
180+
publish:
181+
name: Publish to S3 and flush Akamai
182+
needs: [resolve, build]
183+
if: github.repository == 'NVIDIA/NeMo-Retriever'
184+
runs-on: ubuntu-latest
185+
environment: docs-nvidia-prod
186+
steps:
187+
- name: Checkout FW-CI-templates (publish-docs action)
188+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
189+
with:
190+
repository: NVIDIA-NeMo/FW-CI-templates
191+
ref: ${{ env.FW_CI_TEMPLATES_REF }}
192+
path: FW-CI-templates
193+
sparse-checkout: .github/actions/publish-docs
194+
195+
- name: Publish versioned and latest docs (S3 + Akamai)
196+
uses: ./FW-CI-templates/.github/actions/publish-docs
197+
with:
198+
dry-run: ${{ needs.resolve.outputs.dry_run }}
199+
artifacts-name: ${{ env.ARTIFACT_NAME }}
200+
artifacts-path: docs/site
201+
project-type: single-docset
202+
run-on-version-tag-only: "false"
203+
docs-version-override: ${{ needs.resolve.outputs.docs_version }}
204+
overwrite-latest-on-tag: ${{ needs.resolve.outputs.publish_latest }}
205+
update-version-picker: "true"
206+
request-name: nemo-retriever-docs-${{ github.run_id }}
207+
emails-csv: ${{ needs.resolve.outputs.emails_csv }}
208+
aws-region: ${{ vars.DOCS_AWS_REGION }}
209+
aws-role-to-assume: ${{ secrets.AWS_ASSUME_ROLE_ARN }}
210+
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
211+
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
212+
akamai-host: ${{ secrets.AKAMAI_HOST }}
213+
akamai-client-token: ${{ secrets.AKAMAI_CLIENT_TOKEN }}
214+
akamai-client-secret: ${{ secrets.AKAMAI_CLIENT_SECRET }}
215+
akamai-access-token: ${{ secrets.AKAMAI_ACCESS_TOKEN }}
216+
s3-target-root: ${{ secrets.S3_BUCKET_NAME }}
217+
s3-target-path: ${{ env.S3_TARGET_PATH }}
218+
219+
# publish-docs leaves AWS credentials on the runner; only fetch the redirect file here.
220+
- name: Checkout repository (root redirect)
221+
if: needs.resolve.outputs.dry_run == 'false'
222+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
223+
with:
224+
path: nemo-retriever-src
225+
sparse-checkout: docs/publish/index.html
226+
227+
- name: Upload retriever root index.html
228+
if: needs.resolve.outputs.dry_run == 'false'
229+
env:
230+
S3_TARGET_ROOT: ${{ secrets.S3_BUCKET_NAME }}
231+
run: |
232+
S3_ROOT="${S3_TARGET_ROOT%/}"
233+
DEST="${S3_ROOT}/${{ env.S3_TARGET_PATH }}/index.html"
234+
aws s3 cp --quiet nemo-retriever-src/docs/publish/index.html "${DEST}"

‎docs/overrides-nrl-staging/main.html‎

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

‎docs/overrides/main.html‎

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

‎docs/publish/index.html‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8">
5+
<title>Redirecting</title>
6+
<noscript>
7+
<meta http-equiv="refresh" content="1; url=latest/" />
8+
</noscript>
9+
<script>
10+
window.location.replace(
11+
"latest/" + window.location.search + window.location.hash
12+
);
13+
</script>
14+
</head>
15+
<body>
16+
Redirecting to <a href="latest/">latest/</a>...
17+
</body>
18+
</html>

‎docs/publish/versions.json‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
[
2+
{
3+
"version": "26.5.0",
4+
"title": "26.5.0",
5+
"aliases": [
6+
"latest"
7+
]
8+
},
9+
{
10+
"version": "26.3.0",
11+
"title": "26.3.0",
12+
"aliases": []
13+
},
14+
{
15+
"version": "26.1.2",
16+
"title": "26.1.2",
17+
"aliases": []
18+
},
19+
{
20+
"version": "26.1.1",
21+
"title": "26.1.1",
22+
"aliases": []
23+
},
24+
{
25+
"version": "25.9.0",
26+
"title": "25.9.0",
27+
"aliases": []
28+
},
29+
{
30+
"version": "25.6.3",
31+
"title": "25.6.3",
32+
"aliases": []
33+
},
34+
{
35+
"version": "25.6.2",
36+
"title": "25.6.2",
37+
"aliases": []
38+
},
39+
{
40+
"version": "25.4.2",
41+
"title": "25.4.2",
42+
"aliases": []
43+
},
44+
{
45+
"version": "25.3.0",
46+
"title": "25.3.0",
47+
"aliases": []
48+
}
49+
]

‎docs/sphinx_docs/source/conf.py‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,12 @@
3838
html_theme = "nvidia_sphinx_theme"
3939

4040
html_theme_options = {
41+
# set the start date for copyright
42+
"copyright_override": {"start": 2023},
43+
"public_docs_features": True,
4144
"header_links": [
4245
("Home", "index"),
43-
("GitHub", "https://github.com/NVIDIA/nvidia-sphinx-theme", True, "fab fa-github"),
44-
],
45-
"footer_links": [
46-
("Privacy Policy", "https://www.nvidia.com/en-us/about-nvidia/privacy-policy/"),
47-
("Terms of Use", "https://www.nvidia.com/en-us/about-nvidia/legal-info/"),
46+
("GitHub", "https://github.com/NVIDIA/NeMo-Retriever", True, "fab fa-github"),
4847
],
4948
"show_prev_next": True, # Show next/previous buttons at bottom
5049
}

0 commit comments

Comments
 (0)