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

refactor: keep a single solution to manage preview (#145)

Previously, there were both bash and npm scripts that rely on several nodejs
script. For simplicity, we only have a single bash script that support all
existing options (with a single nodejs script).

The documentation has been improved
  - introduce `--help` in the bash script to display all available options
  - the README better explains how to generate the preview for both development
  and deployment

Bonus: activate Admonitions with github support in the README
parent f8e26c6b
......@@ -5,5 +5,4 @@ node_modules/
*.DS_Store
# generated files
antora-playbook-local-sources.yml
antora-playbook-content-for-preview.yml
= New Bonita Documentation Site
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
// External URIs:
:url-antora: https://antora.org
:url-asciidoctor: https://asciidoctor.org/
......@@ -46,6 +54,13 @@ For more CLI options, see https://docs.antora.org/antora/2.3/cli/options/
==== Building for local developments
[WARNING]
====
The following command https://docs.antora.org/antora/2.3/playbook/runtime-fetch/[fetch the documentation content repositories] each time they are run. +
<<local-content>> or <<preview>> can prevent this to happen.
====
For a site that can be load from local disk
```bash
npm run local:build-static
......@@ -56,7 +71,8 @@ For a site to be served by the development <<http server>>
npm run local:build
```
===== Using local documentation content repository
[[local-content]]
===== Using local documentation content repositories
This activates the https://docs.antora.org/antora/2.3/playbook/author-mode/[Antora author mode]. The local content of the
repository is used instead of fetching the remote one.
......@@ -79,11 +95,28 @@ root
```
====
For more information about the `build-preview.bash` script, see later in this document
```bash
npm run local:build-static:local-content
./build-preview.bash --ci false --type local --local-sources true
```
[[preview]]
==== Building for preview
It is possible to use a script that let's generate the documentation partially or with specific settings for both local
developments or Pull Request previews.
This includes building the documentation using:
- already checkout local documentation content repositories
- single branch for all components
- single branch of a single component
- ....
To know all available options, run
```bash
./build-preview.bash --help
```
==== http server
......
......@@ -5,26 +5,58 @@
########################################################################################################################
set -euo pipefail
function usage() {
launch_command=$(basename "${0}")
echo "Usage: ${launch_command}"
echo " Globals"
echo " --help Display this help"
# most of the arguments in this section are used by the nodejs script
echo " Antora configuration"
echo " --branch <branch-name> When not keeping a single branch by component, the name of the branch to keep"
echo " --component <component-name> When not keeping a single branch by component, the name of the component to keep"
echo " --fetch-sources <boolean> 'true': fetch documentation content sources prior building the documentation. Defaults to 'false' (on CI, fetch is always done)"
echo " --local-sources <boolean> 'true': use locally checkout sources in a working directory along the one of this project (useful to test local changes without push) , otherwise, use antora cache. Defaults to 'false'"
echo " --pr <PR_NUMBER> Number of the Pull Request related to the preview (when apply). Used to display context information within the preview."
echo " --single-branch-per-repo <boolean> 'true': only keep the latest declared branch for each component, 'false': use all branches. Defaults to 'false'"
echo " --site-url <url> Custom Url of the site preview. Defaults to the original url defined in the Antora playbook."
echo " --type <string> If 'local' use html extension in urls to allow local file browsing"
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'"
}
########################################################################################################################
# Parse arguments
########################################################################################################################
runOnCI=true
extraAntoraArgs=
args="$@"
# Help
if [[ "$args" == *"--help"* ]]; then
usage
exit 0
fi
# if arguments contain '--ci false', don't run 'npm ci'
if [[ "$args" != *"--ci false"* ]]; then
echo "Assume script is running on CI environment"
# force fetch, whatever the cli arguments are
extraAntoraArgs="--fetch"
else
echo "Assume script is NOT running on CI environment"
runOnCI=false
fi
# if arguments contain '--type local', use html extension in urls
if [[ "$args" == *"--type local"* ]]; then
extraAntoraArgs="${extraAntoraArgs} --html-url-extension-style default"
fi
echo "extra Antora Args: ${extraAntoraArgs}"
echo "Extra Antora Arguments: ${extraAntoraArgs}"
########################################################################################################################
# PROCESSING
########################################################################################################################
if [[ $runOnCI == "true" ]]; then
echo "Using node $(node --version) and npm $(npm --version)"
npm ci
......
......@@ -6,7 +6,6 @@
"clean": "rimraf build .cache",
"build": "antora --stacktrace --fetch --clean antora-playbook.yml",
"local:build-static": "antora --stacktrace --fetch --html-url-extension-style default antora-playbook.yml",
"local:build-static:local-content": "node scripts/generate-local-sources-antora-playbook.js && antora --stacktrace --fetch --html-url-extension-style default antora-playbook-local-sources.yml",
"local:build": "antora --stacktrace --fetch --url http://localhost:8080 antora-playbook.yml",
"serve": "http-server build/site -c-1 --port 8080"
},
......
......@@ -70,14 +70,49 @@ else {
doc.site.title = `Preview PR #${prNumber}`;
}
// use local sources for the documentation content repostiories
const useLocalSources = getArgument(argv, 'local-sources', false)
console.info(`Use Local Sources: ${useLocalSources}`);
if (useLocalSources === 'true') {
doc.content.sources
.filter(source => source.url.includes('http') || source.url.includes('ssh'))
.forEach(source => {
source.url = `../${(repositoryNameForUrl(source.url))}`
});
}
if (siteUrl) {
doc.site.url = siteUrl;
}
// We want to ensure that wherever a preview is published, Search Engines won't index it
doc.site.robots = 'disallow';
// Allow local file browsing
const previewType = getArgument(argv, 'type', false)
console.info(`Preview Type: ${previewType}`);
if (previewType === 'local') {
doc.urls.html_extension_style = 'default';
}
// Fetch sources
const fetchSources = getArgument(argv, 'fetch-sources', false)
console.info(`Fetch Sources: ${fetchSources}`);
if (fetchSources === 'true') {
doc.runtime.fetch = true
}
console.info('Dumping yaml....');
const generatedYaml = `# Generated from 'antora-playbook.yml'
${(yaml.dump(doc))}`;
fs.writeFileSync(outputFile, generatedYaml);
console.info(`Antora Playbook generated in ${outputFile}`);
function repositoryNameForUrl(url) {
const urlParts = url.split('/');
const repositoryName = urlParts[urlParts.length-1];
return repositoryName.split('.git')[0];
}
const fs = require('fs');
const fse = require('fs-extra');
const yaml = require('js-yaml');
const outputDirectory = '.';
const outputFile = `${outputDirectory}/antora-playbook-local-sources.yml`
console.info('Generating an Antora Playbook for local git sources only');
fse.ensureDirSync(outputDirectory);
fse.removeSync(outputFile);
const doc = yaml.load(fs.readFileSync('antora-playbook.yml', 'utf8'));
console.info('Antora Playbook source file loaded');
doc.content.sources
.filter(source => source.url.includes('http') || source.url.includes('ssh'))
.forEach(source => {
source.url = `../${(repositoryNameForUrl(source.url))}`
});
console.info('Dumping yaml....')
const generatedYaml = `# Generated from 'antora-playbook.yml'
${(yaml.dump(doc))}`;
fs.writeFileSync(outputFile, generatedYaml);
console.info(`Antora Playbook generated in ${outputFile}`);
function repositoryNameForUrl(url) {
const urlParts = url.split('/');
const repositoryName = urlParts[urlParts.length-1];
return repositoryName.split('.git')[0];
}
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