From ceceb36ddd1896ed96492b0355879180c1f10db2 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Mon, 1 Jun 2020 18:00:30 +0200 Subject: [PATCH] docs: improve readme toc structure (#370) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fran Méndez --- .github/templates-list-validator/index.js | 7 +- README.md | 107 +++++++++++----------- 2 files changed, 56 insertions(+), 58 deletions(-) diff --git a/.github/templates-list-validator/index.js b/.github/templates-list-validator/index.js index 5ff3c567c..704ccd34b 100644 --- a/.github/templates-list-validator/index.js +++ b/.github/templates-list-validator/index.js @@ -1,6 +1,7 @@ const github = require('@actions/github'); const core = require('@actions/core'); -const { readFileSync } = require('fs'); +const path = require('path'); +const fs = require('fs'); async function run() { try { @@ -11,7 +12,7 @@ async function run() { const missingTemplates = officialTemplates.filter(str => !templatesListContent.includes(str)); - if (missingTemplates) core.setFailed( + if (missingTemplates.length) core.setFailed( `The following templates are not in the README.md: ${missingTemplates}. Make sure missing templates are added to the list in the README of this repository and also to the website to the list of offecial tools: https://github.com/asyncapi/website/blob/master/content/docs/tooling.md` ); @@ -27,7 +28,7 @@ async function run() { * @return {String} */ function getReadmeContent() { - const readmeContent = readFileSync('../../README.md', 'utf8'); + const readmeContent = fs.readFileSync(path.resolve(__dirname,'../../README.md'), 'utf8'); const startingTag = ''; const startOfOpeningTagIndex = readmeContent.indexOf(`${startingTag}START`); diff --git a/README.md b/README.md index 996cdcd1d..1b54be0cd 100644 --- a/README.md +++ b/README.md @@ -20,14 +20,13 @@ * [Install the CLI](#install-the-cli) * [Update the CLI](#update-the-cli) * [CLI usage](#cli-usage) - * [Examples using the CLI](#examples-using-the-cli) - * [Generator version vs Template version](#generator-version-vs-template-version) - * [You don't like technical requirements for the CLI?](#you-dont-like-technical-requirements-for-the-cli) - + [Run with npx](#run-with-npx) - + [Run with Docker](#run-with-docker) + * [CLI usage examples](#cli-usage-examples) + * [CLI usage with Docker](#cli-usage-with-docker) + * [CLI usage with npx instead of npm](#cli-usage-with-npx-instead-of-npm) - [Using as a module/package](#using-as-a-modulepackage) * [Install the module](#install-the-module) * [Example using the module](#example-using-the-module) +- [Generator version vs Template version](#generator-version-vs-template-version) - [How to create a template](#how-to-create-a-template) - [Contributing](#contributing) - [Contributors ✨](#contributors-%E2%9C%A8) @@ -132,7 +131,7 @@ Options:
-### Examples using the CLI +### CLI usage examples **The shortest possible syntax:** ```bash @@ -167,55 +166,7 @@ It creates a symbolic link to the target directory (`~/my-template` in this case ag asyncapi.yaml https://github.com/asyncapi/html-template.git ``` -### Generator version vs Template version - -The generator is a tool that you can use to generate whatever you want, taking AsyncAPI specification file as an input. A template is a tool that uses Generator features and helpers to specify what should be generated. - -In other words, a template depends on the generator and its features. For example it might work with the latest version of the generator but not the previous ones. - -Owner of the template specifies in the configuration what version of the generator is the template compatible with: -```bash -"generator": ">=0.50.0 <2.0.0", -``` - -The generator doesn't work in case template is not compatible: -```bash -Something went wrong: -Error: This template is not compatible with the current version of the generator (0.50.0). This template is compatible with the following version range: >=0.60.0 <2.0.0. - at Generator.validateTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:678:13) - at Generator.loadTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:663:16) - at Generator.generate (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:146:18) - at processTicksAndRejections (internal/process/task_queues.js:97:5) - at async /Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/cli.js:135:7 -``` - -In case you use generator CLI and a specific template on production, it is safer to lock to a specific version of the template and the generator. - -Instead of generating HTML with latest `html-template` and the generator CLI: -```bash -npm install -g @asyncapi/generator -ag asyncapi.yaml @asyncapi/html-template -o ./docs -``` - -Generate HTML with the version of the `html-template` and the generator CLI that you are happy with: -```bash -npm install -g @asyncapi/generator@0.50.0 -ag asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs -``` - -Before using newer versions of the template, always look at the [changlelog](https://github.com/asyncapi/html-template/releases) first. Generator features are not important for you, just make sure to use the version compatible with the template. - -### You don't like technical requirements for the CLI? - -#### Run with npx - -The [npx](https://www.npmjs.com/package/npx) is very useful when you want to run generator in CI/CD environment. In such scenario you do not want to install generator globally and most environments that provide Node.js and npm, also provide npx out of the box. - -```bash -npx -p @asyncapi/generator ag ./asyncapi.yaml @asyncapi/html-template -``` - -#### Run with Docker +### CLI usage with Docker Install [Docker](https://docs.docker.com/get-docker/) first. Thanks to Docker you do not need Node.js even though the generator is written with it. @@ -231,6 +182,14 @@ docker run --rm -it \ asyncapi/generator -o ./output asyncapi.yml @asyncapi/html-template --force-write ``` +### CLI usage with npx instead of npm + +The [npx](https://www.npmjs.com/package/npx) is very useful when you want to run Generator in CI/CD environment. In such a scenario, you do not want to install generator globally and most environments that provide Node.js and npm, also provide npx out of the box. + +```bash +npx -p @asyncapi/generator ag ./asyncapi.yaml @asyncapi/html-template +``` + ## Using as a module/package ### Install the module @@ -257,6 +216,44 @@ try { See [API documentation](docs/api.md) for more example and full API reference information. +## Generator version vs Template version + +The Generator is a tool that you can use to generate whatever you want, taking an AsyncAPI specification file as the input. A template is a tool that uses Generator features and helpers to specify what should be generated. + +In other words, a template depends on the Generator and its features. For example, it might work with the latest version of the Generator but not the previous ones. + +The owner of the template specifies in the configuration what version of the Generator it is compatible with: +```bash +"generator": ">=0.50.0 <2.0.0", +``` + +The Generator doesn't work in case the template is not compatible: +```bash +Something went wrong: +Error: This template is not compatible with the current version of the generator (0.50.0). This template is compatible with the following version range: >=0.60.0 <2.0.0. + at Generator.validateTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:678:13) + at Generator.loadTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:663:16) + at Generator.generate (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:146:18) + at processTicksAndRejections (internal/process/task_queues.js:97:5) + at async /Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/cli.js:135:7 +``` + +In case you use Generator CLI and a specific template on production, it is safer to lock to a specific version of the template and the Generator. + +Instead of generating HTML with latest `html-template` and the generator CLI: +```bash +npm install -g @asyncapi/generator +ag asyncapi.yaml @asyncapi/html-template -o ./docs +``` + +Generate HTML with the version of the `html-template` and the Generator CLI that you are happy with: +```bash +npm install -g @asyncapi/generator@0.50.0 +ag asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs +``` + +Before using newer versions of the template, always look at the [changelog](https://github.com/asyncapi/html-template/releases) first. Generator features are not important for you, just make sure to use a version compatible with the template. + ## How to create a template To create your own template, for example code generator for some specific language and technology, read [authoring templates](docs/authoring.md) and the [list of templates recipes](docs/templates-recipes.md).