From 4024e7605fe7e7e7ca7ac9253455ac3983ff3fae Mon Sep 17 00:00:00 2001 From: mikaello <2505178+mikaello@users.noreply.github.com> Date: Sat, 2 Apr 2022 19:59:11 +0200 Subject: [PATCH] docs: improve documentation and input validation --- README.md | 39 ++++++++++++++++---------- public/js/schema.js | 22 +++++++++++---- src/cli.js | 67 ++++++++++++++++++++++++++++++++------------- 3 files changed, 90 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index d82a1f1..6412785 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,31 @@ Or without installation: npx @mikaello/avrodoc-plus -i source -o out.html ``` -### Options - -- -i _sourcefolder_ - Pass in a source folder that will recursively parsed and crawled for avsc files -- -o _outputfile_ - The file where the generated doc should be written to -- --title _Avrodoc for ACME_ - The title that will be used in the generated HTML page, deafults to _Avrodoc_. -- -s _external stylesheet less file_ - Your own less file, used to override specific style of your generated page -- --ignore-invalid - Ignore avsc files that can not be parsed as JSON (instead of quiting) - -### Enhancements +## Options + +```text +USAGE: + avrodoc [FLAGS] [OPTIONS] [AVRO FILES...] + +FLAGS: + --ignore-invalid Ignore avsc files that can not be parsed as JSON (instead of quiting) + +OPTIONS: + -i, --input Pass in a source folder that will recursively parsed and crawled for avsc files + -o, --output The file where the generated doc should be written to + --title The title that will be used in the generated HTML page, deafults to "Avrodoc". + -s, --style <file> Your own less file, used to override specific style of your generated page + +ARGS: + <AVRO FILES>... If not --input is given, you can specify individual AVRO files here + +EXAMPLES: + avrodoc --ignore-invalid --input ./schemas --output avrodoc.html --title "My First Avrodoc" + + avrodoc --output avro.html --style my-styles.less avro_schema1.avsc avro_schema2.avsc avro_schema3.avsc +``` + +## Enhancements - support for input folders - support of schema/type search (search by namespace and/or schema/type) diff --git a/public/js/schema.js b/public/js/schema.js index 591b170..4bf79dd 100644 --- a/public/js/schema.js +++ b/public/js/schema.js @@ -130,8 +130,13 @@ AvroDoc.Schema = function (avrodoc, shared_types, schema_json, filename) { } } - // Check type of object. Get all additional arbitrary attributes on the object - // for inclusion in the decorated schema object. + /** + * Check type of object. Get all additional arbitrary attributes on the object + * for inclusion in the decorated schema object. + * + * @param {object} schema + * @return {object} schema + */ function decorateCustomAttributes(schema) { if (schema.annotations !== undefined && schema.annotations !== null) { return schema; @@ -182,12 +187,19 @@ AvroDoc.Schema = function (avrodoc, shared_types, schema_json, filename) { return schema; } - // Takes a node in the schema tree (a JS object) and adds some fields that are useful for - // template rendering. + /** + * Takes a node in the schema tree (a JS object) and adds some fields that are + * useful for template rendering. + * + * @param {object} schema + * @return {object} schema + */ function decorate(schema) { schema.filename = filename; schema["is_" + schema.type] = true; - if (schema.is_error) schema.is_record = true; + if (schema.is_error) { + schema.is_record = true; + } schema.qualified_name = qualifiedName(schema); schema = decorateCustomAttributes(schema); diff --git a/src/cli.js b/src/cli.js index 53a8341..e656b50 100644 --- a/src/cli.js +++ b/src/cli.js @@ -17,6 +17,9 @@ import arg from "arg"; const debug = debugFn("avrodoc:cli"); const argv = arg({ + "--help": Boolean, + "-h": "--help", + "--output": String, "-o": "--output", @@ -31,42 +34,68 @@ const argv = arg({ "--ignore-invalid": Boolean, }); -let inputFiles = null; -let outputFile = null; -let ignoreInvalidSchemas = false; +const usage = `USAGE: + avrodoc [FLAGS] [OPTIONS] [AVRO FILES...] + +FLAGS: + --ignore-invalid Ignore avsc files that can not be parsed as JSON (instead of quiting) + +OPTIONS: + -i, --input <folder> Pass in a source folder that will recursively parsed and crawled for avsc files + -o, --output <file> The file where the generated doc should be written to + --title <title> The title that will be used in the generated HTML page, deafults to "Avrodoc". + -s, --style <file> Your own less file, used to override specific style of your generated page + +ARGS: + <AVRO FILES>... If not --input is given, you can specify individual AVRO files here + +EXAMPLES: + avrodoc --ignore-invalid --input ./schemas --output avrodoc.html --title "My First Avrodoc" + + avrodoc --output avro.html --style my-styles.less avro_schema1.avsc avro_schema2.avsc avro_schema3.avsc +`; + +if ( + argv["--help"] || + (argv._.length === 0 && Object.entries(argv).length === 1) // no params +) { + console.log(usage); + process.exit(0); +} + +let inputFiles = []; -// Determine list of input files file1.avsc file2.avsc if (argv["--input"]) { debug("Collecting all avsc files from root folder ", argv["--input"]); - inputFiles = collectInputFiles(argv["--input"]); -} else if (argv._.length > 0) { - debug("Using passed arguments as inputfiles..."); - inputFiles = argv._; + inputFiles = inputFiles.concat(collectInputFiles(argv["--input"])); } -// Determine whether an output file is specified -if (argv["--output"]) { - outputFile = argv["--output"]; +if (argv._.length > 0) { + debug("Using passed arguments as inputfiles..."); + inputFiles = inputFiles.concat(argv._); } -const extra_less_files = argv["--style"] ? [argv["--style"]] : []; - -if (argv["--ignore-invalid"]) { - ignoreInvalidSchemas = true; -} +const outputFile = argv["--output"]; const pageTitle = argv["--title"]; +const extraLessFile = argv["--style"]; +const ignoreInvalidSchemas = Boolean(argv["--ignore-invalid"]); //valid input? -if (!inputFiles || inputFiles.length === 0 || outputFile === null) { +if (inputFiles.length === 0) { + console.error( + 'Missing input schemata, either specify a folder with "--input" or individual AVRO files. Specify "--help" to see usage.' + ); + process.exit(1); +} else if (outputFile == null) { console.error( - "Usage: avrodoc [-i rootfolder] [my-schema.avsc [another-schema.avsc...]] [-o my-documentation.html] [-s my-style.less] [--ignore-invalid]" + 'Missing output file, specify with "--output" where the resulting HTML should go. Specify "--help" to see usage.' ); process.exit(1); } createAvroDoc( pageTitle, - extra_less_files, + extraLessFile ? [extraLessFile] : [], inputFiles, outputFile, ignoreInvalidSchemas