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

chore(playbook): allow to use locally clone document content repository (#63)

Generate an Antora Playbook from the regular one and change the content sources
configuration.

* Document when we need using local sources git repo
parent 150c5615
......@@ -3,3 +3,6 @@ build/
node_modules/
.cache/
*.DS_Store
# generated files
antora-playbook-local-sources.yml
......@@ -56,6 +56,34 @@ For a site to be served by the development <<http server>>
npm run local:build
```
===== Using local documentation content repository
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.
It provides a fast feedback loop as you don't need to push nor commit content as the current work
[NOTE]
.Repositories location
====
This requires to clone all repository sources locally is the parent folder of this project.
For instance
```
root
|
-- bonita-doc
|
-- bonita-ici-doc
|
-- bonitasoft.github.io
```
====
```bash
npm run local:build-static:local-content
```
==== http server
......
......@@ -17,7 +17,6 @@ content:
# - url: git@github.com:alachambre/antora-source-api.git
# - url: https://github.com/alachambre/antora-sources-test-2.git
# local development: use ../bonita-ici-doc (see also https://docs.antora.org/antora/2.3/playbook/author-mode/)
- url: https://github.com/bonitasoft/bonita-ici-doc.git
branches: [master]
......
......@@ -44,6 +44,29 @@
"through2": "~4.0",
"vinyl": "~2.2",
"vinyl-fs": "~3.0"
},
"dependencies": {
"fs-extra": {
"version": "8.1.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
"integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
"dev": true,
"requires": {
"graceful-fs": "^4.2.0",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
}
},
"js-yaml": {
"version": "3.14.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
"integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
"dev": true,
"requires": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
}
}
}
},
"@antora/content-classifier": {
......@@ -101,6 +124,18 @@
"convict": "~6.0",
"js-yaml": "~3.14",
"json5": "~2.1"
},
"dependencies": {
"js-yaml": {
"version": "3.14.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
"integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
"dev": true,
"requires": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
}
}
}
},
"@antora/redirect-producer": {
......@@ -153,6 +188,19 @@
"gulp-vinyl-zip": "~2.2",
"vinyl": "~2.2",
"vinyl-fs": "~3.0"
},
"dependencies": {
"fs-extra": {
"version": "8.1.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
"integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
"dev": true,
"requires": {
"graceful-fs": "^4.2.0",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
}
}
}
},
"@antora/ui-loader": {
......@@ -173,6 +221,29 @@
"through2": "~4.0",
"vinyl": "~2.2",
"vinyl-fs": "~3.0"
},
"dependencies": {
"fs-extra": {
"version": "8.1.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
"integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
"dev": true,
"requires": {
"graceful-fs": "^4.2.0",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
}
},
"js-yaml": {
"version": "3.14.1",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.1.tgz",
"integrity": "sha512-okMH7OXXJ7YrN9Ok3/SXrnu4iX9yOk+25nqX4imS2npuvTYDmo/QEZoqwZkYaIDk3jVvBOTOIEgEhaLOynBS9g==",
"dev": true,
"requires": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
}
}
}
},
"@iarna/toml": {
......@@ -238,6 +309,12 @@
"integrity": "sha512-UBQJC2pbeyGutIfYmErGc9RaJYnpZ1FHaxuKwb0ahvGiiCkPUf3p67Io+YLPmmv3RHY+mF6JEtNW8FlHsraAaA==",
"dev": true
},
"at-least-node": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz",
"integrity": "sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==",
"dev": true
},
"balanced-match": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.0.tgz",
......@@ -768,14 +845,41 @@
"dev": true
},
"fs-extra": {
"version": "8.1.0",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-8.1.0.tgz",
"integrity": "sha512-yhlQgA6mnOJUKOsRUFsgJdQCvkKhcz8tlZG5HBQfReYZy46OwLcY+Zia0mtdHsOo9y/hP+CxMN0TU9QxoOtG4g==",
"version": "9.0.1",
"resolved": "https://registry.npmjs.org/fs-extra/-/fs-extra-9.0.1.tgz",
"integrity": "sha512-h2iAoN838FqAFJY2/qVpzFXy+EBxfVE220PalAqQLDVsFOHLJrZvut5puAbCdNv6WJk+B8ihI+k0c7JK5erwqQ==",
"dev": true,
"requires": {
"at-least-node": "^1.0.0",
"graceful-fs": "^4.2.0",
"jsonfile": "^4.0.0",
"universalify": "^0.1.0"
"jsonfile": "^6.0.1",
"universalify": "^1.0.0"
},
"dependencies": {
"jsonfile": {
"version": "6.1.0",
"resolved": "https://registry.npmjs.org/jsonfile/-/jsonfile-6.1.0.tgz",
"integrity": "sha512-5dgndWOriYSm5cnYaJNhalLNDKOqFwyDB/rr1E9ZsGciGvKPs8R2xYGCacuf3z6K1YKDz182fd+fY3cn3pMqXQ==",
"dev": true,
"requires": {
"graceful-fs": "^4.1.6",
"universalify": "^2.0.0"
},
"dependencies": {
"universalify": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/universalify/-/universalify-2.0.0.tgz",
"integrity": "sha512-hAZsKq7Yy11Zu1DE0OzWjw7nnLZmJZYTDZZyEFHZdUhV8FkH5MCfoU1XMaxXovpyW5nq5scPqq0ZDP9Zyl04oQ==",
"dev": true
}
}
},
"universalify": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/universalify/-/universalify-1.0.0.tgz",
"integrity": "sha512-rb6X1W158d7pRQBg5gkR8uPaSfiids68LTJQYOtEUhoJUWBdaQHsuT/EUduxXYxcrt4r5PJ4fuHW1MHT6p0qug==",
"dev": true
}
}
},
"fs-mkdirp-stream": {
......@@ -1288,13 +1392,20 @@
}
},
"js-yaml": {
"version": "3.14.0",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-3.14.0.tgz",
"integrity": "sha512-/4IbIeHcD9VMHFqDR/gQ7EdZdLimOvW2DdcxFjdyyZ9NsbS+ccrXqVWDtab/lRl5AlUqmpBx8EhPaWR+OtY17A==",
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.0.0.tgz",
"integrity": "sha512-pqon0s+4ScYUvX30wxQi3PogGFAlUyH0awepWvwkj4jD4v+ova3RiYw8bmA6x2rDrEaj8i/oWKoRxpVNW+Re8Q==",
"dev": true,
"requires": {
"argparse": "^1.0.7",
"esprima": "^4.0.0"
"argparse": "^2.0.1"
},
"dependencies": {
"argparse": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
"dev": true
}
}
},
"json-buffer": {
......
......@@ -6,13 +6,16 @@
"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"
},
"devDependencies": {
"@antora/cli": "^2.3.4",
"@antora/site-generator-default": "^2.3.4",
"fs-extra": "^9.0.1",
"http-server": "^0.12.3",
"js-yaml": "^4.0.0",
"rimraf": "^3.0.2"
}
}
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 a Antora Playbook for local git sources only');
fse.ensureDirSync(outputDirectory);
fse.removeSync(outputFile);
try {
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}`);
} catch (e) {
console.error(e);
}
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