From 104452f3a6750b191f5c0438e35f771377235213 Mon Sep 17 00:00:00 2001 From: Claymore1337 <31853210+Claymore1337@users.noreply.github.com> Date: Tue, 20 Aug 2019 13:36:59 +0200 Subject: [PATCH] feat: disable header.ejs using console args * feat: disable header.ejs over console args Allow the user to disable the header.ejs over console args re #153 * feat: disable header.ejs over console args Add test for the new Parameter and add this option to README.md re #153 * feat: disable header.ejs over console args Moved output for the new test re #153 * feat: disable header.ejs over console args Test fix re #153 * Update README.md Co-Authored-By: Lars Trieloff * Update README.md Co-Authored-By: Lars Trieloff * Update lib/markdownWriter.js Co-Authored-By: Lars Trieloff * feat: disable header.ejs over console args Add the suggested default value for the new parameter re #153 * feat: disable header.ejs over console args Fixed test re #153 fixes #153 --- README.md | 8 + cli.js | 3 + examples/docsWithoutHeader/arrays.schema.md | 254 +++++++++++++++++++ lib/markdownWriter.js | 18 +- spec/examples/withoutHeader/arrays.schema.md | 254 +++++++++++++++++++ spec/lib/integrationTest.spec.js | 32 ++- 6 files changed, 559 insertions(+), 10 deletions(-) create mode 100644 examples/docsWithoutHeader/arrays.schema.md create mode 100644 spec/examples/withoutHeader/arrays.schema.md diff --git a/README.md b/README.md index 35ac04ae..cacaf665 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,14 @@ $ jsonschema2md -d examples/schemas -o examples/docs -v 06 -i temp/myFiles +## Disable header template +In some cases you do not need a header because it does not provide any useful information. With the `--header` (or `-h`) parameter you can disable the inclusion of headers. + +```bash +# run against JSON Schema Draft 06 +$ jsonschema2md -d examples/schemas -o examples/docs -v 06 -h false +``` + ## Using JSON Schema Markdown Tools from `npm` You can conveniently use the JSON Schema Markdown Tools from `npm`. This makes it possible to set up a conversion toolchain for your JSON Schema project that is driven entirely by `npm`. To do so, first define the dependency by adding this to your `"devDependencies"` section of `package.json` diff --git a/cli.js b/cli.js index 6578441b..135ff079 100755 --- a/cli.js +++ b/cli.js @@ -51,6 +51,9 @@ var argv = require('optimist') }) .alias('i', 'i18n') .describe('i', 'path to a locales folder with an en.json file in it. This file will be used for all text parts in all templates') + .alias('h', 'header') + .describe('h', 'if the value is false the header will be skipped') + .default('h', true) .argv; const docs = _.fromPairs(_.toPairs(argv).filter(([ key, value ]) => { return key.startsWith('link-'); }).map(([ key, value ]) => { return [ key.substr(5), value ];})); diff --git a/examples/docsWithoutHeader/arrays.schema.md b/examples/docsWithoutHeader/arrays.schema.md new file mode 100644 index 00000000..67fa8f41 --- /dev/null +++ b/examples/docsWithoutHeader/arrays.schema.md @@ -0,0 +1,254 @@ +# Arrays Properties + +| Property | Type | Required | Nullable | Defined by | +| --------------------------------- | ------------ | ---------- | -------- | ------------------------------------------ | +| [JoinTypelist](#jointypelist) | `array` | Optional | No | Arrays (this schema) | +| [boollist](#boollist) | `boolean[]` | Optional | No | Arrays (this schema) | +| [coordinatelist](#coordinatelist) | `number[][]` | Optional | No | Arrays (this schema) | +| [intlist](#intlist) | `integer[]` | Optional | No | Arrays (this schema) | +| [list](#list) | `string[]` | Optional | No | Arrays (this schema) | +| [listlist](#listlist) | `array[]` | Optional | No | Arrays (this schema) | +| [numlist](#numlist) | `number[]` | Optional | No | Arrays (this schema) | +| [objectlist](#objectlist) | `object[]` | Optional | No | Arrays (this schema) | +| [stringlistlist](#stringlistlist) | `string[][]` | Optional | No | Arrays (this schema) | +| `*` | any | Additional | Yes | this schema _allows_ additional properties | + +## JoinTypelist + +An array of simple objects + +`JoinTypelist` + +- is optional +- type: `array` +- defined in this schema + +### JoinTypelist Type + +Array type: `array` + +All items must be of the type: + +**One** of the following _conditions_ need to be fulfilled. + +#### Condition 1 + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | -------- | +| `foo` | string | Optional | + +#### foo + +A simple string. + +`foo` + +- is optional +- type: `string` + +##### foo Type + +`string` + +##### foo Example + +```json +hello +``` + +#### Condition 2 + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | -------- | +| `bar` | string | Optional | + +#### bar + +A simple string. + +`bar` + +- is optional +- type: `string` + +##### bar Type + +`string` + +##### bar Example + +```json +world +``` + +## boollist + +This is an array + +`boollist` + +- is optional +- type: `boolean[]` +- at least `1` items in the array +- defined in this schema + +### boollist Type + +Array type: `boolean[]` + +All items must be of the type: `boolean` + +## coordinatelist + +This is an array of coordinates in three-dimensional space. + +`coordinatelist` + +- is optional +- type: `number[][]` (nested array) +- no more than `10` items in the array +- defined in this schema + +### coordinatelist Type + +Nested array type: `number[]` + +All items must be of the type: `number` + +- minimum value: `0` +- maximum value: `10` + +A coordinate, specified by `x`, `y`, and `z` values + +## intlist + +This is an array + +`intlist` + +- is optional +- type: `integer[]` +- between `1` and `10` items in the array +- defined in this schema + +### intlist Type + +Array type: `integer[]` + +All items must be of the type: `integer` + +## list + +This is an array + +`list` + +- is optional +- type: `string[]` +- defined in this schema + +### list Type + +Array type: `string[]` + +All items must be of the type: `string` + +## listlist + +This is an array of arrays + +`listlist` + +- is optional +- type: `array[]` (nested array) +- defined in this schema + +### listlist Type + +Nested array type: `array` + +## numlist + +This is an array + +`numlist` + +- is optional +- type: `number[]` +- no more than `10` items in the array +- defined in this schema + +### numlist Type + +Array type: `number[]` + +All items must be of the type: `number` + +- minimum value: `10` + +## objectlist + +An array of simple objects + +`objectlist` + +- is optional +- type: `object[]` +- defined in this schema + +### objectlist Type + +Array type: `object[]` + +All items must be of the type: `object` with following properties: + +| Property | Type | Required | +| -------- | ------- | ------------ | +| `a` | string | **Required** | +| `b` | integer | Optional | + +#### a + +The a property + +`a` + +- is **required** +- type: `string` + +##### a Type + +`string` + +#### b + +The b property + +`b` + +- is optional +- type: `integer` + +##### b Type + +`integer` + +## stringlistlist + +This is an array of arrays of strings + +`stringlistlist` + +- is optional +- type: `string[][]` (nested array) +- defined in this schema + +### stringlistlist Type + +Nested array type: `string[]` + +All items must be of the type: `string` diff --git a/lib/markdownWriter.js b/lib/markdownWriter.js index b50860cc..39eabb90 100644 --- a/lib/markdownWriter.js +++ b/lib/markdownWriter.js @@ -175,17 +175,19 @@ const generateMarkdown = function(filename, schema, schemaPath, outDir, dependen //console.log(dependencyMap); // this structure allows us to have separate templates for each element. Instead of having // one huge template, each block can be built individually - let multi = [ - [ 'frontmatter.ejs', { meta: schema.metaElements } ], - [ 'header.ejs', { + outDir = outDir ? outDir : path.resolve(path.join('.', 'out')); + let multi = []; + multi.push([ 'frontmatter.ejs', { meta: schema.metaElements } ]); + if (!consoleArgs||consoleArgs.header){ + multi.push([ 'header.ejs', { i18n: i18n, schema: schema, dependencies: flatten(dependencyMap), - table: headers(schema, schemaPath, filename, docs).render() } ], - //[ 'divider.ejs', null ], - //[ 'topSchema.ejs', ctx ], - [ 'examples.ejs', { i18n: i18n, examples: stringifyExamples(schema.examples), title: schema.title } ] - ]; + table: headers(schema, schemaPath, filename, docs).render() } ]); + } + //multi.push(['divider.ejs', null ]); + //multi.push(['topSchema.ejs', ctx ]); + multi.push([ 'examples.ejs', { examples: stringifyExamples(schema.examples), title: schema.title, i18n: i18n } ]); const required = []; //to store required of whole schema, even those in definitions // Processing schema.definitions before schema.properties to get any required properties present in definitions diff --git a/spec/examples/withoutHeader/arrays.schema.md b/spec/examples/withoutHeader/arrays.schema.md new file mode 100644 index 00000000..67fa8f41 --- /dev/null +++ b/spec/examples/withoutHeader/arrays.schema.md @@ -0,0 +1,254 @@ +# Arrays Properties + +| Property | Type | Required | Nullable | Defined by | +| --------------------------------- | ------------ | ---------- | -------- | ------------------------------------------ | +| [JoinTypelist](#jointypelist) | `array` | Optional | No | Arrays (this schema) | +| [boollist](#boollist) | `boolean[]` | Optional | No | Arrays (this schema) | +| [coordinatelist](#coordinatelist) | `number[][]` | Optional | No | Arrays (this schema) | +| [intlist](#intlist) | `integer[]` | Optional | No | Arrays (this schema) | +| [list](#list) | `string[]` | Optional | No | Arrays (this schema) | +| [listlist](#listlist) | `array[]` | Optional | No | Arrays (this schema) | +| [numlist](#numlist) | `number[]` | Optional | No | Arrays (this schema) | +| [objectlist](#objectlist) | `object[]` | Optional | No | Arrays (this schema) | +| [stringlistlist](#stringlistlist) | `string[][]` | Optional | No | Arrays (this schema) | +| `*` | any | Additional | Yes | this schema _allows_ additional properties | + +## JoinTypelist + +An array of simple objects + +`JoinTypelist` + +- is optional +- type: `array` +- defined in this schema + +### JoinTypelist Type + +Array type: `array` + +All items must be of the type: + +**One** of the following _conditions_ need to be fulfilled. + +#### Condition 1 + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | -------- | +| `foo` | string | Optional | + +#### foo + +A simple string. + +`foo` + +- is optional +- type: `string` + +##### foo Type + +`string` + +##### foo Example + +```json +hello +``` + +#### Condition 2 + +`object` with following properties: + +| Property | Type | Required | +| -------- | ------ | -------- | +| `bar` | string | Optional | + +#### bar + +A simple string. + +`bar` + +- is optional +- type: `string` + +##### bar Type + +`string` + +##### bar Example + +```json +world +``` + +## boollist + +This is an array + +`boollist` + +- is optional +- type: `boolean[]` +- at least `1` items in the array +- defined in this schema + +### boollist Type + +Array type: `boolean[]` + +All items must be of the type: `boolean` + +## coordinatelist + +This is an array of coordinates in three-dimensional space. + +`coordinatelist` + +- is optional +- type: `number[][]` (nested array) +- no more than `10` items in the array +- defined in this schema + +### coordinatelist Type + +Nested array type: `number[]` + +All items must be of the type: `number` + +- minimum value: `0` +- maximum value: `10` + +A coordinate, specified by `x`, `y`, and `z` values + +## intlist + +This is an array + +`intlist` + +- is optional +- type: `integer[]` +- between `1` and `10` items in the array +- defined in this schema + +### intlist Type + +Array type: `integer[]` + +All items must be of the type: `integer` + +## list + +This is an array + +`list` + +- is optional +- type: `string[]` +- defined in this schema + +### list Type + +Array type: `string[]` + +All items must be of the type: `string` + +## listlist + +This is an array of arrays + +`listlist` + +- is optional +- type: `array[]` (nested array) +- defined in this schema + +### listlist Type + +Nested array type: `array` + +## numlist + +This is an array + +`numlist` + +- is optional +- type: `number[]` +- no more than `10` items in the array +- defined in this schema + +### numlist Type + +Array type: `number[]` + +All items must be of the type: `number` + +- minimum value: `10` + +## objectlist + +An array of simple objects + +`objectlist` + +- is optional +- type: `object[]` +- defined in this schema + +### objectlist Type + +Array type: `object[]` + +All items must be of the type: `object` with following properties: + +| Property | Type | Required | +| -------- | ------- | ------------ | +| `a` | string | **Required** | +| `b` | integer | Optional | + +#### a + +The a property + +`a` + +- is **required** +- type: `string` + +##### a Type + +`string` + +#### b + +The b property + +`b` + +- is optional +- type: `integer` + +##### b Type + +`integer` + +## stringlistlist + +This is an array of arrays of strings + +`stringlistlist` + +- is optional +- type: `string[][]` (nested array) +- defined in this schema + +### stringlistlist Type + +Nested array type: `string[]` + +All items must be of the type: `string` diff --git a/spec/lib/integrationTest.spec.js b/spec/lib/integrationTest.spec.js index 27bc33ba..1631b83c 100644 --- a/spec/lib/integrationTest.spec.js +++ b/spec/lib/integrationTest.spec.js @@ -56,13 +56,14 @@ describe('Compare results', () => { ls.on('close', code => { expect(code).toEqual(0); const files = readdirSync('./spec/examples').filter(item => !(/(^|\/)\.[^\/\.]/g).test(item)); - expect(files.length).toEqual(22); + expect(files.length).toEqual(23); //console.log(readFileSync(path.resolve('./examples/schemas/', 'definitions.schema.json')).toString()); files.forEach(file => { if (statSync('./spec/examples/' + file).isFile()) { const expectedstr = readFileSync(path.resolve('./spec/examples/', file)).toString(); - const actualstr = readFileSync(path.resolve('./examples/docs/', file)).toString(); + let actualstr = readFileSync(path.resolve('./examples/docs/', file)).toString(); + actualstr=actualstr.replace(/\r\n/g, '\n'); expect(actualstr).toEqual(expectedstr, file + ' does not match'); } }); @@ -70,4 +71,31 @@ describe('Compare results', () => { done(); }); }); + it('Run jsonschema2md for a file and do not generate a header', done => { + const ls = spawn('node', [ + 'cli.js', + '-d', + 'examples/schemas/arrays.schema.json', + '-o', + 'examples/docsWithoutHeader', + '-x', + 'examples/generated-schemas', + '--no-header', + '-v', + '06' + ]); + + ls.on('close', code => { + expect(code).toEqual(0); + const files = readdirSync('./spec/examples/withoutHeader').filter(item => !(/(^|\/)\.[^\/\.]/g).test(item)); + files.forEach(file => { + if (statSync('./spec/examples/withoutHeader/' + file).isFile()) { + const expectedstr = readFileSync(path.resolve('./spec/examples/withoutHeader/', file)).toString(); + let actualstr = readFileSync(path.resolve('./examples/docsWithoutHeader/', file)).toString(); + expect(actualstr).toEqual(expectedstr, file + ' does not match'); + } + }); + done(); + }); + }); });