From b48ea2fce0dd9223c548a755811f67a59d3de12b Mon Sep 17 00:00:00 2001 From: Robert Kaussow Date: Thu, 10 Oct 2019 14:59:12 +0200 Subject: [PATCH] add basic readme --- README.md | 185 +++++++++++++++++++++++++++++++++++++++++++ ansibledoctor/Cli.py | 10 +-- 2 files changed, 190 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index b87e2a2..0205951 100644 --- a/README.md +++ b/README.md @@ -3,3 +3,188 @@ [![Build Status](https://cloud.drone.io/api/badges/xoxys/ansible-doctor/status.svg)](https://cloud.drone.io/xoxys/ansible-doctor) [![](https://images.microbadger.com/badges/image/xoxys/ansible-doctor.svg)](https://microbadger.com/images/xoxys/ansible-doctor "Get your own image badge on microbadger.com") ![License](https://img.shields.io/github/license/xoxys/ansible-doctor) + +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 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). + +## Table of Content + +* [Setup](#Setup) + * [Using pip](#Using-pip) + * [Using docker](#Using-docker) +* [Configuration](#Configuration) + * [Default settings](#Default-settings) + * [CLI options](#CLI-options) + * [Environment variables](#Environment-variables) +* [Usage](#Usage) +* [License](#License) +* [Maintainers and Contributors](#Maintainers-and-Contributors) + +--- + +### Setup + +#### Using pip + +```Shell +# From PyPI as unprivilegd user +$ pip install ansible-doctor --user + +# .. or as root +$ 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 +``` + +#### Using docker + +```Shell +docker run \ + -e ANSIBLE_DOCTOR_ROLE_DIR=example/demo-role/ \ + -e ANSIBLE_DOCTOR_OUTPUT_DIR=example/ \ + -e ANSIBLE_DOCTOR_FORCE_OVERWRITE=true \ + -e ANSIBLE_DOCTOR_CUSTOM_HEADER=example/demo-role/HEADER.md \ + -e ANSIBLE_DOCTOR_LOG_LEVEL=info \ + -e PY_COLORS=1 \ + -v $(pwd):/doctor \ + -w /doctor \ + xoxys/ansible-doctor +``` + +Keep in mind, that you have to pass selinux labels (:Z or :z) to your mount option if you are working on a selinux enabled system. + +### Configuration + +`ansible-doctor` comes with default settings which should be sufficient for most users to start, but you can adjust most settings to your needs. + +Changes can be made on different locations which will be processed in the following order (last wins): + +* default config (build-in) +* global config file (path depends on your operating system) +* folder-based config file (.ansibledoctor.yml|.ansibledoctor.yaml|.ansibledoctor in current working dir) +* environment variables +* cli options + +#### Default settings + +```YAML +--- +# default is your current working dir +role_dir: +# don't write anything to filesystem +dry_run: False + +logging: + # possible options debug | info | warning | error | critical + level: "warning" + # you can enable json logging if a parsable output is required + json: False + +# path to write rendered template file +# default is your current working dir +output_dir: +# default is in-build templates dir +template_dir: +template: readme + +# don't ask to overwrite if output file exists +force_overwrite: False +# load custom header from given file and append template output +# to it before write. +custom_header: "" + +exclude_files: [] +# Examples +# exclude_files: +# - molecule/ +# - files/**/*.py +``` + +#### CLI options + +```Shell +$ ansible-doctor --help +usage: ansible-doctor [-h] [-c CONFIG_FILE] [-o OUTPUT_DIR] [-f] [-d] [-v] + [-q] [--version] + role_dir + +Generate documentation from annotated Ansible roles using templates + +positional arguments: + role_dir role directory (default: current working dir) + +optional arguments: + -h, --help show this help message and exit + -c CONFIG_FILE, --config CONFIG_FILE + location of configuration file + -o OUTPUT_DIR, --output OUTPUT_DIR + output base dir + -f, --force force overwrite output file + -d, --dry-run dry run without writing + -v increase log level + -q decrease log level + --version show program's version number and exit +``` + +#### Environment variables + +```Shell +CONFIG_FILE= +ROLE_DIR= +DRY_RUN=false +LOG_LEVEL=warning +LOG_JSON=false +OUTPUT_DIR= +TEMPLATE_DIR= +TEMPLATE=readme +FORCE_OVERWRITE=false +CUSTOM_HEADER= +EXCLUDE_FILES= +# EXCLUDE_FILES=molecule/,files/**/*.py +``` + +### Usage + +```Shell +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! :) + +After the successful check, `ansible-doctor` will try to read some static files into a dictionary: + +* defaults/main.yml +* meta/main.yml + +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. + +```Yaml +# @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 +# Very secure password to login to the docker registry. +# @end +docker_registry_password: "secret" +``` + +These list of pre-defined identifiers is currently available: + +* @meta +* @todo +* @var +* @tag + +### License + +This project is licensed under the GNU v3.0 - see the [LICENSE](https://github.com/xoxys/ansible-doctor/blob/master/LICENSE) file for details. + +### Maintainers and Contributors + +[Robert Kaussow](https://github.com/xoxys) diff --git a/ansibledoctor/Cli.py b/ansibledoctor/Cli.py index 8d1024a..ddebce3 100644 --- a/ansibledoctor/Cli.py +++ b/ansibledoctor/Cli.py @@ -35,13 +35,13 @@ class AnsibleDoctor: # TODO: add function to print to stdout instead of file parser = argparse.ArgumentParser( description="Generate documentation from annotated Ansible roles using templates") - parser.add_argument("role_dir", nargs="?", help="role directory, (default: current working dir)") - parser.add_argument("-c", "--config", nargs="?", dest="config_file", help="location of configuration file") - parser.add_argument("-o", "--output", action="store", dest="output_dir", type=str, + parser.add_argument("role_dir", help="role directory (default: current working dir)") + parser.add_argument("-c", "--config", dest="config_file", help="location of configuration file") + parser.add_argument("-o", "--output", dest="output_dir", action="store", help="output base dir") - parser.add_argument("-f", "--force", action="store_true", default=None, dest="force_overwrite", + parser.add_argument("-f", "--force", dest="force_overwrite", action="store_true", default=None, help="force overwrite output file") - parser.add_argument("-d", "--dry-run", action="store_true", default=None, dest="dry_run", + parser.add_argument("-d", "--dry-run", dest="dry_run", action="store_true", default=None, help="dry run without writing") parser.add_argument("-v", dest="logging.level", action="append_const", const=-1, help="increase log level")