paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 38 Packages Projects Releases Wiki Activity

Merge pull request #26355 from backstage/rugvip/versioned-docs

Browse Source 
microsite: add documentation versioning
This commit is contained in:
Johan Haals
2024-09-04 09:20:19 +02:00
committed by GitHub
parent 9d810d98ff 51273aa2f0
commit 60a2e3c375
5 changed files with 276 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/deploy_microsite.yml
+175 -21
View File
@@ -8,14 +8,148 @@ permissions:
contents: read
jobs:
deploy-microsite-and-storybook:
permissions:
contents: write # for JamesIves/github-pages-deploy-action to push changes in repo
stable:
runs-on: ubuntu-latest
concurrency:
group: stable-reference-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
CI: true
NODE_OPTIONS: --max-old-space-size=8192
outputs:
release: ${{ steps.find-release.outputs.result }}
steps:
- name: Harden Runner
uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
with:
egress-policy: audit
- name: find latest release
uses: actions/github-script@v7
id: find-release
with:
script: |
const { data } = await github.rest.repos.listTags({
owner: context.repo.owner,
repo: context.repo.repo,
per_page: 100,
})
const [{tag}] = data
.map(i => i.name)
.filter(tag => tag.match(/^v\d+\.\d+\.\d+$/))
.map(tag => ({
tag,
val: tag
.slice(1)
.split('.')
.reduce((val, part) => Number(val) * 1000 + Number(part))
}))
.sort((a, b) => b.val - a.val)
return tag
result-encoding: string
- name: checkout latest release
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
ref: refs/tags/${{ steps.find-release.outputs.result }}
- name: use node.js 18.x
uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version: 18.x
registry-url: https://registry.npmjs.org/ # Needed for auth
- name: yarn install
uses: backstage/actions/yarn-install@3c138326f7fcbf253b88170c1f29bae8e975d47c # v0.6.14
with:
cache-prefix: ${{ runner.os }}-v18.x
- name: build API reference
run: yarn build:api-docs
- name: upload API reference
uses: actions/upload-artifact@v4
with:
name: stable-reference
path: docs/reference/
if-no-files-found: error
retention-days: 1
next:
runs-on: ubuntu-latest
concurrency:
group: next-reference-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
env:
CI: true
NODE_OPTIONS: --max-old-space-size=8192
steps:
- name: Harden Runner
uses: step-security/harden-runner@5c7944e73c4c2a096b17a9cb74d65b6c2bbafbde # v2.9.1
with:
egress-policy: audit
- name: checkout master
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: use node.js 18.x
uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version: 18.x
registry-url: https://registry.npmjs.org/ # Needed for auth
- name: yarn install
uses: backstage/actions/yarn-install@3c138326f7fcbf253b88170c1f29bae8e975d47c # v0.6.14
with:
cache-prefix: ${{ runner.os }}-v18.x
- name: build API reference
run: yarn build:api-docs
- name: upload API reference
uses: actions/upload-artifact@v4
with:
name: next-reference
path: docs/reference/
if-no-files-found: error
retention-days: 1
# Also build and upload storybook
- name: storybook yarn install
run: yarn install --immutable
working-directory: storybook
- name: storybook build
run: yarn build-storybook
working-directory: storybook
- name: storybook upload
uses: actions/upload-artifact@v4
with:
name: storybook
path: storybook/dist/
if-no-files-found: error
retention-days: 1
deploy-microsite-and-storybook:
permissions:
contents: write # for JamesIves/github-pages-deploy-action to push changes in repo
runs-on: ubuntu-latest
needs:
- stable
- next
env:
CI: true
NODE_OPTIONS: --max-old-space-size=16384
DOCUSAURUS_SSR_CONCURRENCY: 5
concurrency:
@@ -28,39 +162,59 @@ jobs:
with:
egress-policy: audit
- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
- name: use node.js 18.x
uses: actions/setup-node@1e60f620b9541d16bece96c5465dc8ee9832be0b # v4.0.3
with:
node-version: 18.x
registry-url: https://registry.npmjs.org/ # Needed for auth
# We avoid caching in this workflow, as we're running an install of both the top-level
# dependencies and the microsite. We leave it to the main master workflow to produce the
# cache, as that results in a smaller bundle.
- name: top-level yarn install
run: yarn install --immutable
# Stable docs
- name: checkout latest release
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
ref: refs/tags/${{ needs.stable.outputs.release }}
- name: microsite yarn install
run: yarn install --immutable
working-directory: microsite
- name: storybook yarn install
run: yarn install --immutable
working-directory: storybook
- name: build API reference
run: yarn build:api-docs
- name: download stable reference
uses: actions/download-artifact@v4
with:
name: stable-reference
path: docs/reference
- name: generate stable docs
run: yarn docusaurus docs:version stable
working-directory: microsite
- name: clear API reference
run: rm -r docs/reference
# Next docs
- name: checkout master
uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
with:
clean: false
- name: microsite yarn install
run: yarn install --immutable
working-directory: microsite
- name: download next reference
uses: actions/download-artifact@v4
with:
name: next-reference
path: docs/reference
- name: build microsite
run: yarn build
working-directory: microsite
- name: build storybook
run: yarn build-storybook
working-directory: storybook
- name: move storybook dist into microsite
run: mv storybook/dist/ microsite/build/storybook
- uses: actions/download-artifact@v4
with:
name: storybook
path: microsite/build/storybook
- name: Check the build output
run: ls microsite/build && ls microsite/build/storybook
.gitignore
+3
View File
@@ -42,6 +42,9 @@ coverage
# Bower dependency directory (https://bower.io/)
bower_components
# Documentation reference, generated by build:api-docs
docs/reference
# node-waf configuration
.lock-wscript
docs/.gitignore
-2
View File
@@ -1,2 +0,0 @@
# This is generated by build:api-docs in the root
reference
microsite/docusaurus.config.ts
+63 -5
View File
@@ -21,9 +21,38 @@
import { themes } from 'prism-react-renderer';
import type * as Preset from '@docusaurus/preset-classic';
import { Config } from '@docusaurus/types';
import RedirectPlugin from '@docusaurus/plugin-client-redirects';
const backstageTheme = themes.vsDark;
backstageTheme.plain.backgroundColor = '#232323';
const useVersionedDocs = require('fs').existsSync('versions.json');
// This patches the redirect plugin to ignore the error when it tries to override existing fields.
// This lets us add redirects that only apply to the next docs, while the stable docs still contain the source path.
const PatchedRedirectPlugin: typeof RedirectPlugin = (ctx, opts) => {
const plugin = RedirectPlugin(ctx, opts);
return {
...plugin,
async postBuild(...args) {
try {
await plugin.postBuild(...args);
} catch (error) {
if (
error.message ===
'The redirect plugin is not supposed to override existing files.'
) {
// Bit of a hack to make sure all remaining redirects are written, since the write uses Promise.all
await new Promise(resolve => setTimeout(resolve, 1000));
} else {
throw error;
}
}
},
};
};
const config: Config = {
title: 'Backstage Software Catalog and Developer Platform',
tagline: 'An open source framework for building developer portals',
@@ -57,6 +86,26 @@ const config: Config = {
editUrl: 'https://github.com/backstage/backstage/edit/master/docs/',
path: '../docs',
sidebarPath: 'sidebars.json',
...(useVersionedDocs
? {
includeCurrentVersion: true,
lastVersion: 'stable',
versions: {
stable: {
label: 'Stable',
path: '/',
banner: 'none',
badge: false,
},
current: {
label: 'Next',
path: '/next',
banner: 'unreleased',
badge: true,
},
},
}
: undefined),
},
blog: {
path: 'blog',
@@ -119,9 +168,11 @@ const config: Config = {
};
},
}),
[
'@docusaurus/plugin-client-redirects',
{
ctx =>
PatchedRedirectPlugin(ctx, {
id: '@docusaurus/plugin-client-redirects',
toExtensions: [],
fromExtensions: [],
redirects: [
{
from: '/docs',
@@ -200,8 +251,7 @@ const config: Config = {
to: '/docs/backend-system/core-services/url-reader',
},
],
},
],
}),
[
'docusaurus-pushfeedback',
{
@@ -259,6 +309,14 @@ const config: Config = {
label: 'Community',
position: 'left',
},
...(useVersionedDocs
? [
{
type: 'docsVersionDropdown',
position: 'right' as const,
},
]
: []),
],
},
image: 'img/sharing-opengraph.png',
microsite/sidebars.json
+35 -35
View File
@@ -1,39 +1,4 @@
{
"releases": {
"Release Notes": [
"releases/v1.30.0",
"releases/v1.29.0",
"releases/v1.28.0",
"releases/v1.27.0",
"releases/v1.26.0",
"releases/v1.25.0",
"releases/v1.24.0",
"releases/v1.23.0",
"releases/v1.22.0",
"releases/v1.21.0",
"releases/v1.20.0",
"releases/v1.19.0",
"releases/v1.18.0",
"releases/v1.17.0",
"releases/v1.16.0",
"releases/v1.15.0",
"releases/v1.14.0",
"releases/v1.13.0",
"releases/v1.12.0",
"releases/v1.11.0",
"releases/v1.10.0",
"releases/v1.9.0",
"releases/v1.8.0",
"releases/v1.7.0",
"releases/v1.6.0",
"releases/v1.5.0",
"releases/v1.4.0",
"releases/v1.3.0",
"releases/v1.2.0",
"releases/v1.1.0",
"releases/v1.0.0"
]
},
"docs": {
"Overview": [
"overview/what-is-backstage",
@@ -556,5 +521,40 @@
"contribute/project-structure"
],
"References": ["references/glossary"]
},
"releases": {
"Release Notes": [
"releases/v1.30.0",
"releases/v1.29.0",
"releases/v1.28.0",
"releases/v1.27.0",
"releases/v1.26.0",
"releases/v1.25.0",
"releases/v1.24.0",
"releases/v1.23.0",
"releases/v1.22.0",
"releases/v1.21.0",
"releases/v1.20.0",
"releases/v1.19.0",
"releases/v1.18.0",
"releases/v1.17.0",
"releases/v1.16.0",
"releases/v1.15.0",
"releases/v1.14.0",
"releases/v1.13.0",
"releases/v1.12.0",
"releases/v1.11.0",
"releases/v1.10.0",
"releases/v1.9.0",
"releases/v1.8.0",
"releases/v1.7.0",
"releases/v1.6.0",
"releases/v1.5.0",
"releases/v1.4.0",
"releases/v1.3.0",
"releases/v1.2.0",
"releases/v1.1.0",
"releases/v1.0.0"
]
}
}