Unverified Commit 65b2dbd9 authored by Thomas Bouffard's avatar Thomas Bouffard Committed by GitHub
Browse files

test: allow use of project document content and default ui bundle (#297)

Provide document content directly in the project for testing purpose. The site
is fast to build with this content.
It lets test UI bundle change, Antora upgrade, site structure and much more.
It is also possible to build the site with the Antora Default UI for comparison
with the Bonita Theme.
parent 112a5d32
......@@ -68,7 +68,7 @@ This includes building the documentation using:
* already checkout local documentation content repositories
* single branch for all components
* single branch of a single component
* a set of branches of various components. This lets validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* a set of branches of various components. It lets validate https://docs.antora.org/antora/2.3/page/version-and-component-xrefs/[references between pages that belong to different docs components and/or versions]
* ....
To know all available options, run
......@@ -112,7 +112,7 @@ Then, this custom playbook is passed to the Antora CLI along with specific optio
[[local-content]]
==== Using local documentation content repositories
===== Using local documentation content repositories
This activates the https://docs.antora.org/antora/2.3/playbook/author-mode/[Antora author mode]. +
Antora uses the locally cloned repositories as they are on your local machine instead of cloning them from their remote location.
......@@ -149,6 +149,20 @@ This can be achieved by running
./build-preview-dev.bash --local-sources ....
----
===== Using test documentation content
To play with settings, validate the UI Bundle, experiment AsciiDoc syntax and much more, the `bonita-documentation-site` repository provides
a test site structure with documentation content.
The generation site generation is very fast, so using this content reduces the feedback loop.
This can be achieved by running
[source,shell script]
----
./build-preview-dev.bash --use-test-sources ....
----
[[local-ui-bundle]]
===== Using local UI Bundle
......@@ -190,6 +204,20 @@ For a faster loop, don't forget you can build the UI Bundle and the preview by c
<ui_bundle_build_command> ; ./build-preview-dev.bash --local-ui-bundle ...
----
===== Using the Default Antora UI
Sometimes, you need to compare the site rendering with this bundle if you suspect a bug in the Bonita documentation theme.
This can be achieved by running
[source,shell script]
----
./build-preview-dev.bash --default-ui-bundle ...
----
If you want to ensure you use the latest version of the bundle pass `--default-ui-bundle snapshot`. Otherwise, a cache
version is used. For more details, see the https://docs.antora.org/antora/2.3/playbook/ui-bundle-url/#snapshot[Antora Documentation]
==== http dev server
......
......@@ -17,6 +17,7 @@ function usage() {
echo " - use-all-repositories"
echo " - single-branch-per-repo"
echo " - use-multi-repositories"
echo " - use-test-sources"
echo "If no specific options: single branch per component"
echo ""
echo "Globals"
......@@ -27,6 +28,7 @@ function usage() {
echo " --component <component-name> Name of the component when keeping a single branch per component"
echo " --component-with-branches <form> Components and branches when using 'Multiple Repositories'."
echo " Pass one argument per component. For instance, --component-with-branches bcd:3.4 --component-with-branches bonita:7.11,2021.1"
echo " --default-ui-bundle <parameter> If set, use the Antora Default UI. If set to 'snapshot', fetch the bundle instead of retrieving it from the cache. Defaults to 'false'"
echo " --fetch-sources <boolean> 'true': fetch documentation content sources prior building the documentation. Defaults to 'false' (on CI, fetch is always done)"
echo " --force-production-navbar <boolean> 'true': use the regular navbar instead of the preview one. Defaults to 'false'"
echo " --hide-edit-page-links <boolean> 'true': hide all edit page links (useful when generating documentation archive). Defaults to 'false'"
......@@ -41,6 +43,7 @@ function usage() {
echo " If set to 'netlify', use the configuration for the whole Netlify environment (for use with the dev server)."
echo " --use-all-repositories <boolean> If set to 'true', use all sources repositories and branches defined in the production Antora playbook. Defaults to 'false'"
echo " --use-multi-repositories <boolean> If set to 'true', use several repositories and branches passed with the --component-with-branches options. Defaults to 'false'"
echo " --use-test-sources <boolean> If set to 'true', use documentation stored in the bonita-documentation-site repository (for testing). Defaults to 'false'"
echo "Environment configuration"
echo " --ci <boolean> 'false': assume the script is running on local dev machine and don't run some setup commands. Defaults to 'true'"
......
......@@ -53,6 +53,7 @@ function getArgumentAsArray(args, argName, isMandatory) {
const useAllComponents = getArgument(argv, 'use-all-repositories', false);
const useSingleBranchPerComponent = getArgument(argv, 'single-branch-per-repo', false);
const useMultiComponents = getArgument(argv, 'use-multi-repositories', false);
const useTestSources = getArgument(argv, 'use-test-sources', false);
const siteUrl = getArgument(argv, 'site-url', false)
const prNumber = getArgument(argv, 'pr', false)
const siteTitle = getArgument(argv, 'site-title', false)
......@@ -85,7 +86,7 @@ else if (useMultiComponents) {
const componentsWithBranches = getArgumentAsArray(argv, 'component-with-branches', true);
console.info('Components with branches:', componentsWithBranches);
const sources = []
const sources = [];
for (let componentWithBranches of componentsWithBranches) {
const split = componentWithBranches.split(":");
const repoUrl = getRepoUrl(split[0]);
......@@ -94,6 +95,25 @@ else if (useMultiComponents) {
}
doc.content.sources = sources;
}
else if (useTestSources) {
console.info('Documentation content: use test sources');
doc.content.sources = [{
url: './',
branches: ['HEAD'],
start_paths: [
'test/documentation-content/bcd/3.4',
'test/documentation-content/bcd/3.5',
'test/documentation-content/bonita/v0',
'test/documentation-content/bonita/v1-for-2022.2-alpha',
'test/documentation-content/bonita/v7.11',
'test/documentation-content/bonita/v2021.1',
'test/documentation-content/bonita/v2021.2',
'test/documentation-content/bonita/v2022.1-beta',
'test/documentation-content/cloud/latest',
'test/documentation-content/labs/latest',
],
}];
}
// single branch of a single component (pr preview)
else {
console.info('Documentation content: single branch of a single component');
......@@ -130,6 +150,14 @@ if (useLocalUIBundle) {
doc.ui.bundle.url = '../bonita-documentation-theme/build/ui-bundle.zip';
}
// use the Antora Default UI bundle
const useDefaultUIBundle = getArgument(argv, 'default-ui-bundle', false)
console.info(`Use Default Antora UI Bundle: ${useDefaultUIBundle}`);
if (useDefaultUIBundle) {
doc.ui.bundle.url = 'https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable';
doc.ui.bundle.snapshot = useDefaultUIBundle === 'snapshot';
}
if (siteUrl) {
doc.site.url = (siteUrl === 'DISABLED') ? undefined: siteUrl;
......
name: bcd
title: Bonita Continuous Delivery
version: 3.4
asciidoc:
attributes:
bcdVersion: '3.4.5' # latest available maintenance version
bonitaDocVersion: '2021.1'
# General site configuration
page-editable: true
nav:
- modules/ROOT/taxonomy.adoc
= Home version
I am the home of {page-component-title} {page-component-version}
* BCD version: {bcdVersion}
* Bonita Doc version: {bonitaDocVersion}
= Page 01
:page-aliases: old-page-01.adoc
Content
* BCD
** xref:page-01.adoc[Page 01]
** xref:page-02.adoc[Page 02]
** xref:page-03.adoc[Page 03]
name: bcd
title: Bonita Continuous Delivery
version: 3.5
asciidoc:
attributes:
bcdVersion: '3.5.0' # latest available maintenance version
bonitaDocVersion: '2021.2'
# General site configuration
page-editable: true
nav:
- modules/ROOT/taxonomy.adoc
= Home version
I am the home of {page-component-title} {page-component-version}
* BCD version: {bcdVersion}
* Bonita Doc version: {bonitaDocVersion}
= Page 01
:page-aliases: old-page-01.adoc
Content
* BCD
** xref:page-01.adoc[Page 01]
** xref:page-02.adoc[Page 02]
** xref:page-03.adoc[Page 03]
name: bonita
title: Bonita
version: 0 # Antora advises using string for versions (https://antora.zulipchat.com/#narrow/stream/282400-users/topic/.E2.9C.94.20Antora.203.20-.20component.20version.200.20set.20as.20number/near/263559638)
display_version: Archives
start_page: ROOT:archives.adoc
asciidoc:
attributes:
page-editable: true
page-out-of-support: false
page-hide-search-bar: true
nav:
- modules/ROOT/nav.adoc
name: bonita
title: Bonita
version: 1
display_version: 2022.2-alpha
prerelease: alpha
asciidoc:
attributes:
bonitaVersion: 2022.2
bonitaTechnicalVersion: '7.15.0' # latest public community version
javadocVersion: 7.15
crowdinBonitaVersion: 7.15
# page attributes
page-editable: true
page-next-release: true
page-hide-search-bar: true
nav:
- modules/ROOT/taxonomy.adoc
= Home
I am the home of a pre-release of {page-component-title} {bonitaVersion}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment