From 5e306a8aae129a1c84eef985ba1d9601c02a53a1 Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Tue, 2 Jun 2020 22:17:46 +0200 Subject: [PATCH] add docs validation to ci --- .dictionary | 22 ++++++++++++++++ .drone.jsonnet | 36 +++++++++++++++++++++++++- .drone.yml | 31 ++++++++++++++++++---- .markdownlint.yml | 4 +++ CHANGELOG.md | 4 ++- README.md | 8 +++--- docs/content/_index.md | 8 +++--- docs/content/configuration/defaults.md | 4 ++- docs/content/setup/docker.md | 2 +- docs/content/setup/pip.md | 4 ++- docs/content/usage/_index.md | 8 +++--- 11 files changed, 110 insertions(+), 21 deletions(-) create mode 100644 .dictionary create mode 100644 .markdownlint.yml diff --git a/.dictionary b/.dictionary new file mode 100644 index 0000000..e7d132f --- /dev/null +++ b/.dictionary @@ -0,0 +1,22 @@ +([a-zA-Z0-9]+[_=])+\S+ +@\S+ +.py +Ansible +Bott +CLI +Jinja2 +Kaussow +PyPI +YAML +Yaml +ansible-.+ +basename +cli +config +dir +SELinux +subfolder +sudo +xoxys +option1:option2 +todo diff --git a/.drone.jsonnet b/.drone.jsonnet index 06babac..a47af40 100644 --- a/.drone.jsonnet +++ b/.drone.jsonnet @@ -212,6 +212,40 @@ local PipelineDocs = { limit: 1, }, steps: [ + { + name: 'markdownlint', + image: 'node:lts-alpine', + commands: [ + 'npm install -g markdownlint-cli', + "markdownlint 'docs/content/**/*.md' 'README.md'", + ], + environment: { + FORCE_COLOR: true, + NPM_CONFIG_LOGLEVEL: 'error', + }, + }, + { + name: 'spellcheck', + image: 'node:lts-alpine', + commands: [ + 'npm install -g spellchecker-cli', + "spellchecker --files 'docs/content/**/*.md' 'README.md' -d .dictionary -p spell indefinite-article syntax-urls --no-suggestions", + ], + environment: { + FORCE_COLOR: true, + NPM_CONFIG_LOGLEVEL: 'error', + }, + }, + { + name: 'link-validation', + image: 'xoxys/link-validator', + commands: [ + 'link-validator -ro', + ], + environment: { + LINK_VALIDATOR_BASE_DIR: 'exampleSite/public', + }, + }, { name: 'assets', image: 'byrnedo/alpine-curl', @@ -221,7 +255,7 @@ local PipelineDocs = { ], }, { - name: 'test', + name: 'build', image: 'klakegg/hugo:0.59.1-ext-alpine', commands: [ 'cd docs/ && hugo-official', diff --git a/.drone.yml b/.drone.yml index 7ec9729..dbdae1c 100644 --- a/.drone.yml +++ b/.drone.yml @@ -338,13 +338,38 @@ concurrency: limit: 1 steps: +- name: markdownlint + image: node:lts-alpine + commands: + - npm install -g markdownlint-cli + - markdownlint 'docs/content/**/*.md' 'README.md' + environment: + FORCE_COLOR: true + NPM_CONFIG_LOGLEVEL: error + +- name: spellcheck + image: node:lts-alpine + commands: + - npm install -g spellchecker-cli + - spellchecker --files 'docs/content/**/*.md' 'README.md' -d .dictionary -p spell indefinite-article syntax-urls --no-suggestions + environment: + FORCE_COLOR: true + NPM_CONFIG_LOGLEVEL: error + +- name: link-validation + image: xoxys/link-validator + commands: + - link-validator -ro + environment: + LINK_VALIDATOR_BASE_DIR: exampleSite/public + - name: assets image: byrnedo/alpine-curl commands: - mkdir -p docs/themes/hugo-geekdoc/ - curl -L https://github.com/xoxys/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C docs/themes/hugo-geekdoc/ --strip-components=1 -- name: test +- name: build image: klakegg/hugo:0.59.1-ext-alpine commands: - cd docs/ && hugo-official @@ -431,8 +456,4 @@ trigger: depends_on: - docs ---- -kind: signature -hmac: 4cccf7f253f9396b3447ed1a5027b9f1aa68d7211ddbfaf89ae7df43e509891a - ... diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000..9927db2 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,4 @@ +--- +default: True +MD013: False +MD041: False diff --git a/CHANGELOG.md b/CHANGELOG.md index 39cfd4b..62ff5f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2 +1,4 @@ * INTERNAL - * maintenance and refactoring release, no changes + * add markdown linting to CI (markdownlint-cli) + * add spellchecking to CI (spellcheck-cli) + * add broken link check to CI (broken-link-checker) diff --git a/README.md b/README.md index 0cd0e62..51e9421 100644 --- a/README.md +++ b/README.md @@ -3,15 +3,15 @@ [![Build Status](https://img.shields.io/drone/build/xoxys/ansible-doctor?logo=drone)](https://cloud.drone.io/xoxys/ansible-doctor) [![Docker Hub](https://img.shields.io/badge/docker-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/xoxys/ansible-doctor) [![Python Version](https://img.shields.io/pypi/pyversions/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) -[![PyPi Status](https://img.shields.io/pypi/status/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) -[![PyPi Release](https://img.shields.io/pypi/v/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) +[![PyPI Status](https://img.shields.io/pypi/status/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) +[![PyPI Release](https://img.shields.io/pypi/v/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) [![License: MIT](https://img.shields.io/github/license/xoxys/ansible-doctor)](LICENSE) This project is based on the idea (and at some parts on the code) of [ansible-autodoc](https://github.com/AndresBott/ansible-autodoc) by Andres Bott so credits goes to him for his work. -_ansible-doctor_ is a simple annotation like documentation generator based on Jinja2 templates. While _ansible-doctor_ comes with a default template called `readme`, it is also possible to write your own templates. This gives you the ability to customize the output and render the data to every format you like (e.g. html or xml). +_ansible-doctor_ is a simple annotation like documentation generator based on Jinja2 templates. While _ansible-doctor_ comes with a default template called `readme`, it is also possible to write your own templates. This gives you the ability to customize the output and render the data to every format you like (e.g. HTML or XML). -_ansible-doctor_ is designed to work within your CI pipeline to complete your testing and deployment workflow. Releases are available as Python Packages on [GitHub](https://github.com/xoxys/ansible-doctor/releases) or [PyPI](https://pypi.org/project/ansible-doctor/) and as Docker Image on [DockerHub](https://hub.docker.com/r/xoxys/ansible-doctor). +_ansible-doctor_ is designed to work within your CI pipeline to complete your testing and deployment workflow. Releases are available as Python Packages on [GitHub](https://github.com/xoxys/ansible-doctor/releases) or [PyPI](https://pypi.org/project/ansible-doctor/) and as Docker Image on [Docker Hub](https://hub.docker.com/r/xoxys/ansible-doctor). You can find the full documentation at [https://ansible-doctor.geekdocs.de](https://ansible-doctor.geekdocs.de/). diff --git a/docs/content/_index.md b/docs/content/_index.md index d99c132..35b5436 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -5,12 +5,12 @@ title: Documentation [![Build Status](https://img.shields.io/drone/build/xoxys/ansible-doctor?logo=drone)](https://cloud.drone.io/xoxys/ansible-doctor/) [![Docker Hub](https://img.shields.io/badge/docker-latest-blue.svg?logo=docker&logoColor=white)](https://hub.docker.com/r/xoxys/ansible-doctor/) [![Python Version](https://img.shields.io/pypi/pyversions/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) -[![PyPi Status](https://img.shields.io/pypi/status/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) -[![PyPi Release](https://img.shields.io/pypi/v/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) +[![PyPI Status](https://img.shields.io/pypi/status/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) +[![PyPI Release](https://img.shields.io/pypi/v/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/) [![License: MIT](https://img.shields.io/github/license/xoxys/ansible-doctor)](LICENSE) This project is based on the idea (and at some parts on the code) of [ansible-autodoc](https://github.com/AndresBott/ansible-autodoc) by Andres Bott so credits goes to him for his work. -_ansible-doctor_ is a simple annotation like documentation generator based on Jinja2 templates. While _ansible-doctor_ comes with a default template called `readme`, it is also possible to write your own templates. This gives you the ability to customize the output and render the data to every format you like (e.g. html or xml). +_ansible-doctor_ is a simple annotation like documentation generator based on Jinja2 templates. While _ansible-doctor_ comes with a default template called `readme`, it is also possible to write your own templates. This gives you the ability to customize the output and render the data to every format you like (e.g. HTML or XML). -_ansible-doctor_ is designed to work within your CI pipeline to complete your testing and deployment workflow. Releases are available as Python Packages at [GitHub](https://github.com/xoxys/ansible-doctor/releases) or [PyPI](https://pypi.org/project/ansible-doctor/) and as Docker Image at [DockerHub](https://hub.docker.com/r/xoxys/ansible-doctor). +_ansible-doctor_ is designed to work within your CI pipeline to complete your testing and deployment workflow. Releases are available as Python Packages at [GitHub](https://github.com/xoxys/ansible-doctor/releases) or [PyPI](https://pypi.org/project/ansible-doctor/) and as Docker Image at [Docker Hub](https://hub.docker.com/r/xoxys/ansible-doctor). diff --git a/docs/content/configuration/defaults.md b/docs/content/configuration/defaults.md index 2534e6f..2f1a14e 100644 --- a/docs/content/configuration/defaults.md +++ b/docs/content/configuration/defaults.md @@ -2,13 +2,14 @@ title: Default settings --- + {{< highlight YAML "linenos=table" >}} --- # default is your current working dir role_dir: # default is the basename of 'role_name' role_name: -# don't write anything to filesystem +# don't write anything to file system dry_run: False logging: @@ -36,3 +37,4 @@ exclude_files: [] # - molecule/ # - files/**/*.py {{< /highlight >}} + diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md index 3555e5e..314d881 100644 --- a/docs/content/setup/docker.md +++ b/docs/content/setup/docker.md @@ -18,5 +18,5 @@ docker run \ {{< hint info >}} **Info**\ -Keep in mind, that you have to pass selinux labels (:Z or :z) to your mount option if you are working on selinux enabled systems. +Keep in mind, that you have to pass SELinux labels (:Z or :z) to your mount option if you are working on SELinux enabled systems. {{< /hint >}} diff --git a/docs/content/setup/pip.md b/docs/content/setup/pip.md index 8b8665a..1add415 100644 --- a/docs/content/setup/pip.md +++ b/docs/content/setup/pip.md @@ -3,8 +3,9 @@ title: Using pip --- + {{< highlight Shell "linenos=table" >}} -# From PyPI as unprivilegd user +# From PyPI as unprivileged user $ pip install ansible-doctor --user # .. or as root @@ -13,3 +14,4 @@ $ sudo pip install ansible-doctor # From Wheel file $ pip install https://github.com/xoxys/ansible-doctor/releases/download/v0.1.1/ansible_doctor-0.1.1-py2.py3-none-any.whl {{< /highlight >}} + diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md index ff6439b..e3a87c3 100644 --- a/docs/content/usage/_index.md +++ b/docs/content/usage/_index.md @@ -6,7 +6,7 @@ title: Usage ansible-doctor FOLDER ``` -If you don't pass a folder to *ansible-doctor* your current working directory will be used. The first step is to identify if the given folder is an ansible role. This check is very simple, if the folder contains a subfolder called `tasks` is MUST be an ansible role! :) +If you don't pass a folder to *ansible-doctor* your current working directory will be used. The first step is to identify if the given folder is an Ansible role. This check is very simple, if the folder contains a subfolder called `tasks` is MUST be an Ansible role! :) After the successful check, *ansible-doctor* will try to read some static files into a dictionary: @@ -15,19 +15,21 @@ After the successful check, *ansible-doctor* will try to read some static files This will be the base result set which is used as data source for every output template. Without any work, you will get at least a documentation about available variables and some meta information. Theses basic information can be expanded with a set of available annotations. In general, an annotation is a comment with an identifier. This identifier is followed by colon separated options and ends with a value. + {{< highlight Yaml "linenos=table" >}} # @identifier option1:option2: # @var docker_registry_password:example: "%8gv_5GA?" # @var docker_registry_password:description: Very secure password to login to the docker registry # @var docker_registry_password:description: > -# You can also write it as multiline description +# You can also write it as multi line description # Very secure password to login to the docker registry. # @end docker_registry_password: "secret" {{< /highlight >}} + -These list of pre-defined identifiers is currently available: +These list of predefined identifiers is currently available: * @meta * @todo