From 04894ceeaaaf20e0c49bdb8b364ddaa3eb2c7c53 Mon Sep 17 00:00:00 2001 From: Andreas Martin <6525873+about-code@users.noreply.github.com> Date: Sat, 5 Dec 2020 20:49:03 +0100 Subject: [PATCH] feat(cli): New parameter --init to generate a config file with all options and defaults (#126) * Bump test suite version * test: New test case. * test: New baseline. --- bin/index.js | 22 ++++++- conf.schema.json | 57 ++++++++--------- doc/templates/README.md | 62 +++++++++++-------- .../config-cli/arg-init/docs/document.md | 22 +++++++ .../config-cli/arg-init/docs/glossary.md | 5 ++ .../config-cli/arg-init/document.md | 22 +++++++ .../config-cli/arg-init/glossary.md | 5 ++ .../glossarify-md-effective.conf.json | 4 +- test/package-lock.json | 2 +- test/package.json | 37 +++++------ 10 files changed, 156 insertions(+), 82 deletions(-) create mode 100644 test/input/config-cli/arg-init/docs/document.md create mode 100644 test/input/config-cli/arg-init/docs/glossary.md create mode 100644 test/output-expected/config-cli/arg-init/document.md create mode 100644 test/output-expected/config-cli/arg-init/glossary.md diff --git a/bin/index.js b/bin/index.js index 9985f35f..c6dcb392 100755 --- a/bin/index.js +++ b/bin/index.js @@ -15,11 +15,16 @@ const banner = │ glossarify-md v${version} │ └──────────────────────────┘ `; -console.log(banner); // _/ CLI \_____________________________________________________________________ const cli = { - "config": { + "init": { + alias: "new" + ,description: "Generate a complete configuration file with default values." + ,type: "boolean" + ,default: false + } + ,"config": { alias: "c" ,description: "Path to config file, e.g. './glossarify-md.conf.json'." ,type: "string" @@ -46,10 +51,14 @@ const cli = { }; const argv = minimist(proc.argv.slice(2), cli); +if (!argv.init) { + // print banner only without --init to prevent writing banner to config. + console.log(banner); +} // --help (or no args at all) if (argv.help || proc.argv.length === 2) { printOpts(cli); - process.exit(0); + proc.exit(0); } // --config @@ -103,9 +112,16 @@ opts = merge(optsDefault, opts, { } }); +// --init +if (argv.init) { + console.log(JSON.stringify(opts, null, 2)); + proc.exit(0); +} + // Resolve 2nd arg paths relative to 1st arg paths... opts.baseDir = path.resolve(confDir, opts.baseDir); opts.outDir = path.resolve(opts.baseDir, opts.outDir); + validateOpts(opts); // _/ Drop old stuff \__________________________________________________________ diff --git a/conf.schema.json b/conf.schema.json index 6f4f2b6b..fc16e052 100644 --- a/conf.schema.json +++ b/conf.schema.json @@ -3,18 +3,20 @@ "$id": "https://raw.githubusercontent.com/about-code/glossarify-md/v5.0.0/conf.schema.json", "type": "object", "properties": { + "$schema": { + "type": "string", + "default": "./node_modules/glossarify-md/conf.schema.json" + }, "baseDir": { "description": "Path to directory where to search for the glossary file and markdown files. All paths in a config file will be relative to *baseDir*. *baseDir* itself is relative to the location of the config file or the current working directory when provided via command line.", "type": "string", - "alias": "d", - "default": "" + "default": "./docs" }, "baseUrl": { "description": "The base url to use when creating absolute links to glossary.", "type": "string", "format": "url", - "alias": "b", - "default": "http://127.0.0.1" + "default": "" }, "excludeFiles": { "description": "An array of files or file name patterns that should not be included in any processing.", @@ -22,7 +24,6 @@ "items": { "type": "string" }, - "alias": "e", "default": ["node_modules", ".git"] }, "force": { @@ -43,7 +44,6 @@ "items": { "$ref": "#/$defs/GlossariesOpts" }, - "alias": "g", "default": [ { "file": "./glossary.md", "termHint": ""} ] @@ -51,7 +51,6 @@ "ignoreCase": { "description": "Find and link every occurrence of a term no matter how it is spelled.", "type": "boolean", - "alias": "i", "default": false }, "includeFiles": { @@ -60,7 +59,6 @@ "items": { "type": "string" }, - "alias": "f", "default": ["."] }, "indexing": { @@ -83,7 +81,6 @@ "items": { "type": "string" }, - "alias": "r", "default": [] }, "linking": { @@ -93,25 +90,21 @@ "relative", "absolute" ], - "alias": "l", "default": "relative" }, "outDir": { "description": "Path to directory where to write processed files to.", "type": "string", - "alias": "o", - "default": "" + "default": "./docs-glossarified" }, "outDirDropOld": { "description": "If true, remove old 'outDir' before creating a new one. Otherwise just overwrite old files. Default: true", "type": "boolean", - "alias": "", "default": true }, "reportNotMentioned": { "description": "Report on terms which exist in a glossary but have neither been mentioned directly nor with any of its aliases.", "type": "boolean", - "alias": "", "default": false }, "dev": { @@ -148,6 +141,24 @@ } } }, + "GlossariesOpts": { + "type": "object", + "properties": { + "file": { + "description": "Name of the glossary file. Conventional default is 'glossary.md'", + "type": "string" + }, + "termHint": { + "description": "A symbol to append to a link to denote that the term refers to a glossary term.", + "type": "string" + }, + "sort": { + "description": "If present, sort terms in output glossary. Default: None. See also i18n options.", + "type": "string", + "enum": ["asc", "desc"] + } + } + }, "IndexFileOpts": { "type": "object", "properties": { @@ -213,24 +224,6 @@ } } }, - "GlossariesOpts": { - "type": "object", - "properties": { - "file": { - "description": "Name of the glossary file. Conventional default is 'glossary.md'", - "type": "string" - }, - "termHint": { - "description": "A symbol to append to a link to denote that the term refers to a glossary term.", - "type": "string" - }, - "sort": { - "description": "If present, sort terms in output glossary. Default: None. See also i18n options.", - "type": "string", - "enum": ["asc", "desc"] - } - } - }, "DevOpts": { "type": "object", "properties": { diff --git a/doc/templates/README.md b/doc/templates/README.md index 3b8eb5e9..0e33a6d9 100644 --- a/doc/templates/README.md +++ b/doc/templates/README.md @@ -147,39 +147,50 @@ Some syntactic positions of a term are **excluded** from being linked to the glo Having a configuration file is the recommended way of configuring [glossarify-md]. A minimal configuration may look like: -*glossarify-md.conf.json* (minimal): +### Minimal Example + +> **Since v5.0.0** + +*glossarify-md.conf.json* ```json { "$schema": "./node_modules/glossarify-md/conf.schema.json", "baseDir": "./src", - "outDir": "../target", - "outDirDropOld": true, - "glossaries": [ - { "file": "./glossary.md" }, - ], - "includeFiles": ["."], - "excludeFiles": ["node_modules"], - "linking": "relative" + "outDir": "../target" } ``` -**Note:** All paths (except of `$schema`) are interpreted relative to `baseDir`. `baseDir` itself is relative to the location of the config file or current working directory. More options see [Additional Features](#additional-features) or [Options](#options) below. -### Overriding via Command Line +### Initialize with Default Values + +> **Since v5.0.0** + +You can generate a config file with all options and default values by running the command: +~~~ +npx glossarify-md --init > glossarify-md.conf.json +~~~ + +> **Note:** All paths (except of `$schema`) are interpreted relative to `baseDir`. +> +> `baseDir` itself is relative to the location of the config file or Current Working Directory (CWD). More options see [Additional Features](#additional-features) or [Options](#options) below. + +### Configure via Command Line + +> **Since v4.0.0** Use `--shallow` or `--deep` 1. to provide a configuration solely via command line -2. to merge a configuration with your config file or the implicit default config in `./node_modules/glossarify-md/conf.json.schema` +2. to merge a configuration with a config file -Use `--shallow` to *replace* simple top-level options: +*Example: use `--shallow` to *replace* simple top-level options:* ~~~ glossarify-md --config ./glossarify-md.conf.json --shallow "{ 'baseDir':'./src', 'outDir':'../target' }" ~~~ -Use `--shallow` to *replace* complex nested options like `glossaries` alltogether: +*Example: use `--shallow` to *replace* complex nested options like `glossaries` alltogether:* ~~~ glossarify-md @@ -187,7 +198,7 @@ glossarify-md --shallow "{ 'glossaries': [{'file':'./replace.md'}] }" ~~~ -Use `--deep` to *extend* complex nested options, e.g. to *add* another array item to `glossaries` in the config file write: +*Example: use `--deep` to *extend* complex nested options, e.g. to *add* another array item to `glossaries` in the config file write:* ~~~ glossarify-md @@ -546,34 +557,33 @@ Enable support for markdown footnote syntax as defined at ` +- **Since:** v3.5.0 -> **Important:** The `string` value range is *deprecated*. It will be kept throughout all versions of v3.x but is eventually going to be removed. Please use the object value range as shown in the example. +If available, generates a list from HTML anchors exposing the configured `class` attribute. See section [Additional Features](https://github.com/about-code/glossarify-md#lists) for an example. #### `generateFiles.listOfFigures` - **Range:** `{file: string, [title: string, class: string]}` - **Since:** v3.3.0 -If available, generates a list of figures with links to sections where the figures have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-figures) for a configuration example. +Generates a list of figures with links to sections where the figures have been mentioned. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-figures) for a configuration example. #### `generateFiles.listOfTables` - **Range:** `{file: string, [title: string, class: string]}` - **Since:** v3.4.0 -If available, generates a list of tables. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-tables) for an example. - -#### `generateFiles.listOf` - -- **Range:** `Array<{class: string, file: string, [title: string]}>` -- **Since:** v3.5.0 - -If available, generates a list from HTML anchors exposing the configured `class` attribute. See section [Additional Features](https://github.com/about-code/glossarify-md#lists) for an example. +Generates a list of tables. See section [Additional Features](https://github.com/about-code/glossarify-md#list-of-tables) for an example. #### `glossaries` - **Range:** `Array<{file: string, [termHint: string], [sort: string]}>` +- **Default:** [{ "file": "./glossary.md", "termHint": "" }] A list of glossary configuations, each with a path to the glossary file. Every glossary may have an optional *termHint*. A *termHint* is a symbol character diff --git a/test/input/config-cli/arg-init/docs/document.md b/test/input/config-cli/arg-init/docs/document.md new file mode 100644 index 00000000..0b02a3f3 --- /dev/null +++ b/test/input/config-cli/arg-init/docs/document.md @@ -0,0 +1,22 @@ +# Test Case + +GIVEN + +- a directory `docs` +- a markdown file `./docs/document.md` +- a markdown file `./docs/glossary.md` +- a glossary term INIT +- a command line (multiple lines for readability only) + + ~~~ + npx glossarify-md --init > glossarify-md.conf.json + && npx glossarify-md --config ./glossarify-md.conf.json` + ~~~ + +THEN + +- the files MUST be processable without errors + +AND + +- the term should be replaced with a link to its glossary definition. diff --git a/test/input/config-cli/arg-init/docs/glossary.md b/test/input/config-cli/arg-init/docs/glossary.md new file mode 100644 index 00000000..009329ab --- /dev/null +++ b/test/input/config-cli/arg-init/docs/glossary.md @@ -0,0 +1,5 @@ +# Glossary + +## INIT + +Initialize a configuration via `npx glossarify-md --init`. diff --git a/test/output-expected/config-cli/arg-init/document.md b/test/output-expected/config-cli/arg-init/document.md new file mode 100644 index 00000000..1e5bc117 --- /dev/null +++ b/test/output-expected/config-cli/arg-init/document.md @@ -0,0 +1,22 @@ +# [Test Case](#test-case) + +GIVEN + +- a directory `docs` +- a markdown file `./docs/document.md` +- a markdown file `./docs/glossary.md` +- a glossary term [INIT][1] +- a command line (multiple lines for readability only) + + npx glossarify-md --init > glossarify-md.conf.json + && npx glossarify-md --config ./glossarify-md.conf.json` + +THEN + +- the files MUST be processable without errors + +AND + +- the term should be replaced with a link to its glossary definition. + +[1]: ./glossary.md#init "Initialize a configuration via npx glossarify-md --init." diff --git a/test/output-expected/config-cli/arg-init/glossary.md b/test/output-expected/config-cli/arg-init/glossary.md new file mode 100644 index 00000000..e6bfb757 --- /dev/null +++ b/test/output-expected/config-cli/arg-init/glossary.md @@ -0,0 +1,5 @@ +# [Glossary](#glossary) + +## [INIT](#init) + +Initialize a configuration via `npx glossarify-md --init`. diff --git a/test/output-expected/config-cli/deep-defaults/glossarify-md-effective.conf.json b/test/output-expected/config-cli/deep-defaults/glossarify-md-effective.conf.json index 1ff70d9a..6a8462d2 100644 --- a/test/output-expected/config-cli/deep-defaults/glossarify-md-effective.conf.json +++ b/test/output-expected/config-cli/deep-defaults/glossarify-md-effective.conf.json @@ -1,4 +1,5 @@ { + "$schema": "../../../../conf.schema.json", "baseDir": "{CWD}/output-actual/config-cli/deep-defaults", "baseUrl": "file://localhost", "excludeFiles": [ @@ -34,6 +35,5 @@ "reportNotMentioned": false, "dev": { "effectiveConfFile": "./glossarify-md-effective.conf.json" - }, - "$schema": "../../../../conf.schema.json" + } } diff --git a/test/package-lock.json b/test/package-lock.json index c59687b1..bf022778 100644 --- a/test/package-lock.json +++ b/test/package-lock.json @@ -1,6 +1,6 @@ { "name": "glossarify-md-testsuite", - "version": "4.0.0", + "version": "5.0.0", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/test/package.json b/test/package.json index e2320b63..0d515812 100644 --- a/test/package.json +++ b/test/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "glossarify-md-testsuite", - "version": "4.0.0", + "version": "5.0.0", "description": "glossarify-md test scripts", "author": "Andreas Martin", "license": "MIT", @@ -42,23 +42,24 @@ "test_21": "npx . --config ./input/config-cli/arg-shallow/glossarify-md.conf.json --shallow \"{'baseUrl': 'cli://localhost', 'linking': 'absolute', 'glossaries':[{'file':'./glossary2.md'}] }\"", "test_22": "npx . --config ./input/config-cli/arg-deep/glossarify-md.conf.json --deep \"{'glossaries':[{'file':'./glossary2.md'}]}\"", "test_23": "npx . --config ./input/config-cli/deep-defaults/glossarify-md.conf.json", - "test_24": "npx . --config ./input/config-indexFile/glossary-in-subdir/glossarify-md.conf.json", - "test_25": "npx . --config ./input/config-indexFile/index-in-subdir/glossarify-md.conf.json", - "test_26": "npx . --config ./input/config-indexFile/term-link-to-section/glossarify-md.conf.json", - "test_27": "npx . --config ./input/config-indexFile/multiple-glossaries/glossarify-md.conf.json", - "test_28": "npx . --config ./input/config-indexFile/config-title/glossarify-md.conf.json", - "test_29": "npx . --config ./input/count-term-occurrences/glossarify-md.conf.json", - "test_30": "npx . --config ./input/glossary-crosslinks/glossarify-md.conf.json", - "test_31": "npx . --config ./input/config-indexing/groupByHeadingDepth-missing/glossarify-md.conf.json", - "test_32": "npx . --config ./input/config-indexing/groupByHeadingDepth-0/glossarify-md.conf.json", - "test_33": "npx . --config ./input/config-indexing/groupByHeadingDepth-1/glossarify-md.conf.json", - "test_34": "npx . --config ./input/config-indexing/groupByHeadingDepth-2/glossarify-md.conf.json", - "test_35": "npx . --config ./input/config-listOfFigures/image-reference/glossarify-md.conf.json", - "test_36": "npx . --config ./input/config-listOfFigures/option-title-missing/glossarify-md.conf.json", - "test_37": "npx . --config ./input/config-listOfFigures/option-with-listOf-combined/glossarify-md.conf.json", - "test_38": "npx . --config ./input/config-listOfTables/glossarify-md.conf.json", - "test_39": "npx . --config ./input/config-listOf/glossarify-md.conf.json", - "test_40": "npx . --config ./input/config-indexFile/issue-75-formatted-headings/glossarify-md.conf.json", + "test_24": "npx . --init > ./input/config-cli/arg-init/conf.gitignore.json && npx . --config ./input/config-cli/arg-init/conf.gitignore.json --shallow \"{ 'outDir': '../../../../output-actual/config-cli/arg-init/' }\"", + "test_25": "npx . --config ./input/config-indexFile/glossary-in-subdir/glossarify-md.conf.json", + "test_26": "npx . --config ./input/config-indexFile/index-in-subdir/glossarify-md.conf.json", + "test_27": "npx . --config ./input/config-indexFile/term-link-to-section/glossarify-md.conf.json", + "test_28": "npx . --config ./input/config-indexFile/multiple-glossaries/glossarify-md.conf.json", + "test_29": "npx . --config ./input/config-indexFile/config-title/glossarify-md.conf.json", + "test_30": "npx . --config ./input/count-term-occurrences/glossarify-md.conf.json", + "test_31": "npx . --config ./input/glossary-crosslinks/glossarify-md.conf.json", + "test_32": "npx . --config ./input/config-indexing/groupByHeadingDepth-missing/glossarify-md.conf.json", + "test_33": "npx . --config ./input/config-indexing/groupByHeadingDepth-0/glossarify-md.conf.json", + "test_34": "npx . --config ./input/config-indexing/groupByHeadingDepth-1/glossarify-md.conf.json", + "test_35": "npx . --config ./input/config-indexing/groupByHeadingDepth-2/glossarify-md.conf.json", + "test_36": "npx . --config ./input/config-listOfFigures/image-reference/glossarify-md.conf.json", + "test_37": "npx . --config ./input/config-listOfFigures/option-title-missing/glossarify-md.conf.json", + "test_38": "npx . --config ./input/config-listOfFigures/option-with-listOf-combined/glossarify-md.conf.json", + "test_39": "npx . --config ./input/config-listOfTables/glossarify-md.conf.json", + "test_40": "npx . --config ./input/config-listOf/glossarify-md.conf.json", + "test_41": "npx . --config ./input/config-indexFile/issue-75-formatted-headings/glossarify-md.conf.json", "postsuite": "git diff --minimal --color --no-index --ignore-cr-at-eol ./output-expected ./output-actual | node ../bin/test.js", "postat": "git diff --minimal --color --no-index --ignore-cr-at-eol ./output-expected ./output-actual | node ../bin/test.js", "new-baseline": "rm -r ./output-expected && mv ./output-actual ./output-expected",