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

.gitignore

@@ -3,3 +3,6 @@ build/
 node_modules/
 .cache/
 *.DS_Store
+
+# generated files
+antora-playbook-local-sources.yml

README.adoc

@@ -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
 

antora-playbook.yml

@@ -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]
 

package-lock.json

@@ -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": {

package.json

@@ -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"
   }
 }

scripts/generate-local-sources-antora-playbook.js

+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];
+}