'rakosh extract gatsby' becomes 'rakosh gatsby', plus some more documentation

Author: Duncan Rance

.github/workflows/my-mine.yml

@@ -53,7 +53,7 @@ jobs:
       - name: extract and build gatsby site
         run: |
           mkdir ./staticsite
-          ./cli/main.js extract gatsby my-mine examples/my-mine/cust-prod.json ./staticsite -v --no-build
+          ./cli/main.js gatsby my-mine examples/my-mine/cust-prod.json ./staticsite -v --no-build
           cd ./staticsite
           yarn
           yarn list

cli/extract.js cli/gatsby.jscli/extract.js renamed to cli/gatsby.js

@@ -14,17 +14,12 @@ const log = require('loglevel')
 
 log.setLevel('WARN')
 
-exports.command = 'extract <format> <mine> <sitecustom> <directory>'
+exports.command = 'gatsby <mine> <sitecustom> <directory>'
 
-exports.describe = 'Extract the data from a mine into some output format'
+exports.describe = 'Extract the data from a mine into a Gatsby.js site layout'
 
 exports.builder = (yargs) => {
   return yargs
-    .positional('format', {
-      describe: 'The output format of the extraction',
-      string: true,
-      choices: ['gatsby']
-    })
     .positional('mine', {
       describe: 'The name of the mine to extract',
       string: true
@@ -76,12 +71,10 @@ exports.handler = async function (argv) {
 
     log.info(`extracting to ${argv.directory}`)
 
-    if (argv.format === 'gatsby') {
-      await copyTemplates(argv.directory, argv.sitecustom)
-      await extractNuggets(db, argv.directory)
-      await generateMineMap(db, argv.directory)
-      if (argv.build) buildSite(argv.directory)
-    }
+    await copyTemplates(argv.directory, argv.sitecustom)
+    await extractNuggets(db, argv.directory)
+    await generateMineMap(db, argv.directory)
+    if (argv.build) buildSite(argv.directory)
   } catch (err) {
     log.error(`ERROR: ${err}`)
     process.exit(1)

cli/main.js

@@ -5,7 +5,7 @@ const { hideBin } = require('yargs/helpers')
 
 yargs(hideBin(process.argv))
   .command(require('./deposit'))
-  .command(require('./extract'))
+  .command(require('./gatsby'))
   .command(require('./uuid'))
   .demandCommand(1)
   .option('verbose', {

docs/cli.md

@@ -5,3 +5,5 @@ order: 3
 ---
 
 ## Command Line Interface
+
+The Command Line Interface program is called `rakosh`.

docs/cli/cli.md

@@ -1,7 +1,13 @@
 ---
 _key: 234d483d-1e22-4c6c-8b7a-5b44d5325c90
+order: 1
+nuggets:
+  - 228d144f-b0b7-4375-85a5-f5c96eb6fa99
+  - da4fc47f-d5a1-421f-8ed8-299343f4a0e2
+  - 8e03a31c-4624-4c1c-bf7c-fb6d9ddbcbae
+  - 0179441b-3aea-4753-9671-76bcd2f107a7
 ---
 
 ## CLI
 
-The Command Line Interface program is called `rakosh`.
+All the Command Line Interface nuggets:

docs/cli/deposit.md

@@ -0,0 +1,35 @@
+---
+_key: da4fc47f-d5a1-421f-8ed8-299343f4a0e2
+order: 3
+---
+
+### Deposit
+
+The `deposit` command iterates over files and directories to build the structure of a rakosh mine in ArangoDB.
+
+The files and directories are required to be in a particular layout. The layout is versioned to allow for later changes. See [FS Layout](./8e03a31c-4624-4c1c-bf7c-fb6d9ddbcbae).
+
+#### Help Text
+
+```text
+rakosh deposit <directory> [options]
+
+Deposit content from the filesystem into a mine
+
+Positionals:
+  directory  Directory containing a rakosh mine layout     [string] [required]
+
+Options:
+      --help     Show help                                 [boolean]
+      --version  Show version number                       [boolean]
+  -v, --verbose  Run with verbose output                   [boolean]
+  -r, --replace  Replace the existing mine if it exists    [boolean] [default: false]
+```
+
+#### Example
+
+Deposit from a directory called `examples/my-mine` with verbose output and replacing any existing version of `my-mine`:
+
+```sh
+rakosh deposit examples/my-mine -r -v
+```

docs/cli/extract.md

@@ -0,0 +1,37 @@
+---
+_key: 0179441b-3aea-4753-9671-76bcd2f107a7
+order: 5
+---
+
+### Extract
+
+The extraction command use the data in ArangoDB to generate content various formats.
+
+#### Gatsby
+
+Currently the only supported extraction format is a Gatsby.js site:
+
+```text
+rakosh gatsby <mine> <sitecustom> <directory>
+
+Extract the data from a mine into a Gatsby.js site layout
+
+Positionals:
+  mine        The name of the mine to extract                         [required]
+  sitecustom  A JSON file for site customizations            [string] [required]
+  directory   Target directory into which to extract the data[string] [required]
+
+Options:
+      --help     Show help                                             [boolean]
+      --version  Show version number                                   [boolean]
+  -v, --verbose  Run with verbose output                               [boolean]
+      --build    Run the build (use --no-build to not) [boolean] [default: true]
+```
+
+##### Example
+
+Extract from the `docs` mine, using customizations from `docs/cust-dev.json`, into a directory called `heap`. Run with verbose output and do not run `npm build` for gatsby:
+
+```sh
+rakosh gatsby docs docs/cust-dev.json heap --no-build -v
+```

docs/cli/fs_layout.md

@@ -0,0 +1,25 @@
+---
+_key: 8e03a31c-4624-4c1c-bf7c-fb6d9ddbcbae
+order: 4
+---
+
+#### FS Layout
+
+##### Adit
+
+The root node of the graph is called the "adit" -- an entrance to a mine.
+
+The directory pointed to by the `rakosh deposit` command must contain a markdown file with the following front matter:
+
+```yaml
+---
+_key: adit
+fs_layout: '1.1'
+---
+```
+
+`fs_layout` is a version identifier that indicates the layout of these files and directories. The `rakosh` tool checks that it can interpret the given layout.
+
+##### Passages And Nuggets
+
+Directories become Passages and markdown files become Nuggets. If there is a markdown file with front matter `passage: <directory-name>` then its content will be added to the Passage rather than become a Nugget. This file must be in the same directory as the passage directory.

docs/cli/help_text.md

@@ -0,0 +1,23 @@
+---
+_key: 228d144f-b0b7-4375-85a5-f5c96eb6fa99
+order: 2
+---
+
+### Help Text
+
+```text
+rakosh <command>
+
+Commands:
+  rakosh deposit <directory> [options]              Deposit content from the filesystem into a mine
+  rakosh gatsby <mine> <sitecustom> <directory>     Extract the data from a mine into some output format
+  <sitecustom> <directory>
+  rakosh uuid                                       Generate a UUID
+
+Options:
+      --help     Show help                          [boolean]
+      --version  Show version number                [boolean]
+  -v, --verbose  Run with verbose output            [boolean]
+
+Go to https://github.com/orval/rakosh for more information
+```

docs/concepts.md

@@ -7,6 +7,7 @@ nuggets:
   - 1f36fe64-eef9-4226-b837-0f9c35814405
   - 055dc260-16c0-4d6b-9b84-4b4e6be23ef0
   - 3b3b4658-80e2-4087-b219-6c9f9def0bef
+  - 5f459053-1f3b-46ad-9fdd-2843c898e476
 ---
 
 ## Concepts