github
/
ansible-doctor
mirror of https://github.com/thegeeklab/ansible-doctor.git
0
0
Fork 0
Code Issues Projects Releases Wiki Activity

add docs

This commit is contained in:
Robert Kaussow 2020-01-16 11:27:46 +01:00
parent 7292e0ef37
commit 32f40b56f3
15 changed files with 625 additions and 283 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

494
.drone.jsonnet
View File

@ -1,300 +1,350 @@
local PythonVersion(pyversion="3.5") = {
name: "python" + std.strReplace(pyversion, '.', '') + "-pytest",
image: "python:" + pyversion,
pull: "always",
environment: {
PY_COLORS: 1
},
commands: [
"pip install -r test-requirements.txt -qq",
"pip install -qq .",
"ansible-doctor --help",
],
depends_on: [
"clone",
],
local PythonVersion(pyversion='3.5') = {
name: 'python' + std.strReplace(pyversion, '.', '') + '-pytest',
image: 'python:' + pyversion,
environment: {
PY_COLORS: 1,
},
commands: [
'pip install -r test-requirements.txt -qq',
'pip install -qq .',
'ansible-doctor --help',
],
depends_on: [
'clone',
],
};
local PipelineLint = {
kind: "pipeline",
name: "lint",
platform: {
os: "linux",
arch: "amd64",
},
steps: [
{
name: "flake8",
image: "python:3.7",
pull: "always",
environment: {
PY_COLORS: 1
},
commands: [
"pip install -r test-requirements.txt -qq",
"pip install -qq .",
"flake8 ./ansibledoctor",
],
},
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**", "refs/pull/**"],
kind: 'pipeline',
name: 'lint',
platform: {
os: 'linux',
arch: 'amd64',
},
steps: [
{
name: 'flake8',
image: 'python:3.7',
environment: {
PY_COLORS: 1,
},
commands: [
'pip install -r test-requirements.txt -qq',
'pip install -qq .',
'flake8 ./ansibledoctor',
],
},
],
trigger: {
ref: ['refs/heads/master', 'refs/tags/**', 'refs/pull/**'],
},
};
local PipelineTest = {
kind: "pipeline",
name: "test",
platform: {
os: "linux",
arch: "amd64",
},
steps: [
PythonVersion(pyversion="3.5"),
PythonVersion(pyversion="3.6"),
PythonVersion(pyversion="3.7"),
PythonVersion(pyversion="3.8-rc"),
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**", "refs/pull/**"],
},
depends_on: [
"lint",
],
kind: 'pipeline',
name: 'test',
platform: {
os: 'linux',
arch: 'amd64',
},
steps: [
PythonVersion(pyversion='3.5'),
PythonVersion(pyversion='3.6'),
PythonVersion(pyversion='3.7'),
PythonVersion(pyversion='3.8-rc'),
],
depends_on: [
'lint',
],
trigger: {
ref: ['refs/heads/master', 'refs/tags/**', 'refs/pull/**'],
},
};
local PipelineSecurity = {
kind: "pipeline",
name: "security",
platform: {
os: "linux",
arch: "amd64",
},
steps: [
{
name: "bandit",
image: "python:3.7",
pull: "always",
environment: {
PY_COLORS: 1
},
commands: [
"pip install -r test-requirements.txt -qq",
"pip install -qq .",
"bandit -r ./ansibledoctor -x ./ansibledoctor/tests",
],
},
],
depends_on: [
"test",
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**", "refs/pull/**"],
kind: 'pipeline',
name: 'security',
platform: {
os: 'linux',
arch: 'amd64',
},
steps: [
{
name: 'bandit',
image: 'python:3.7',
environment: {
PY_COLORS: 1,
},
commands: [
'pip install -r test-requirements.txt -qq',
'pip install -qq .',
'bandit -r ./ansibledoctor -x ./ansibledoctor/tests',
],
},
],
depends_on: [
'test',
],
trigger: {
ref: ['refs/heads/master', 'refs/tags/**', 'refs/pull/**'],
},
};
local PipelineBuildPackage = {
kind: "pipeline",
name: "build-package",
platform: {
os: "linux",
arch: "amd64",
kind: 'pipeline',
name: 'build-package',
platform: {
os: 'linux',
arch: 'amd64',
},
steps: [
{
name: 'build',
image: 'python:3.7',
commands: [
'python setup.py sdist bdist_wheel',
],
},
steps: [
{
name: "build",
image: "python:3.7",
pull: "always",
commands: [
"python setup.py sdist bdist_wheel",
]
},
{
name: "checksum",
image: "alpine",
pull: "always",
commands: [
"cd dist/ && sha256sum * > ../sha256sum.txt"
],
},
{
name: "publish-github",
image: "plugins/github-release",
pull: "always",
settings: {
overwrite: true,
api_key: { "from_secret": "github_token"},
files: ["dist/*", "sha256sum.txt"],
title: "${DRONE_TAG}",
note: "CHANGELOG.md",
},
when: {
ref: [ "refs/tags/**" ],
},
},
{
name: "publish-pypi",
image: "plugins/pypi",
pull: "always",
settings: {
username: { "from_secret": "pypi_username" },
password: { "from_secret": "pypi_password" },
repository: "https://upload.pypi.org/legacy/",
skip_build: true
},
when: {
ref: [ "refs/tags/**" ],
},
},
],
depends_on: [
"security",
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**", "refs/pull/**"],
{
name: 'checksum',
image: 'alpine',
commands: [
'cd dist/ && sha256sum * > ../sha256sum.txt',
],
},
{
name: 'publish-github',
image: 'plugins/github-release',
settings: {
overwrite: true,
api_key: { from_secret: 'github_token' },
files: ['dist/*', 'sha256sum.txt'],
title: '${DRONE_TAG}',
note: 'CHANGELOG.md',
},
when: {
ref: ['refs/tags/**'],
},
},
{
name: 'publish-pypi',
image: 'plugins/pypi',
settings: {
username: { from_secret: 'pypi_username' },
password: { from_secret: 'pypi_password' },
repository: 'https://upload.pypi.org/legacy/',
skip_build: true,
},
when: {
ref: ['refs/tags/**'],
},
},
],
depends_on: [
'security',
],
trigger: {
ref: ['refs/heads/master', 'refs/tags/**', 'refs/pull/**'],
},
};
local PipelineBuildContainer(arch="amd64") = {
kind: "pipeline",
name: "build-container-" + arch,
local PipelineBuildContainer(arch='amd64') = {
kind: 'pipeline',
name: 'build-container-' + arch,
platform: {
os: "linux",
os: 'linux',
arch: arch,
},
steps: [
{
name: "build",
image: "python:3.7",
pull: "always",
name: 'build',
image: 'python:3.7',
commands: [
"python setup.py bdist_wheel",
]
'python setup.py bdist_wheel',
],
},
{
name: "dryrun",
image: "plugins/docker:18-linux-" + arch,
pull: "always",
name: 'dryrun',
image: 'plugins/docker:18-linux-' + arch,
settings: {
dry_run: true,
dockerfile: "Dockerfile",
repo: "xoxys/ansible-doctor",
username: { "from_secret": "docker_username" },
password: { "from_secret": "docker_password" },
dockerfile: 'Dockerfile',
repo: 'xoxys/ansible-doctor',
username: { from_secret: 'docker_username' },
password: { from_secret: 'docker_password' },
},
when: {
ref: ["refs/pull/**"],
ref: ['refs/pull/**'],
},
},
{
name: "publish",
image: "plugins/docker:18-linux-" + arch,
pull: "always",
name: 'publish',
image: 'plugins/docker:18-linux-' + arch,
settings: {
auto_tag: true,
auto_tag_suffix: arch,
dockerfile: "Dockerfile",
repo: "xoxys/ansible-doctor",
username: { "from_secret": "docker_username" },
password: { "from_secret": "docker_password" },
dockerfile: 'Dockerfile',
repo: 'xoxys/ansible-doctor',
username: { from_secret: 'docker_username' },
password: { from_secret: 'docker_password' },
},
when: {
ref: ["refs/heads/master", "refs/tags/**"],
ref: ['refs/heads/master', 'refs/tags/**'],
},
},
],
depends_on: [
"security",
'security',
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**", "refs/pull/**"],
ref: ['refs/heads/master', 'refs/tags/**', 'refs/pull/**'],
},
};
local PipelineDocs = {
kind: 'pipeline',
name: 'docs',
platform: {
os: 'linux',
arch: 'amd64',
},
concurrency: {
limit: 1,
},
steps: [
{
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',
image: 'klakegg/hugo:0.59.1-ext-alpine',
commands: [
'cd docs/ && hugo-official',
],
},
{
name: 'freeze',
image: 'appleboy/drone-ssh',
settings: {
host: { from_secret: 'ssh_host' },
key: { from_secret: 'ssh_key' },
script: [
'cp -R /var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de/ /var/www/virtual/geeklab/html/ansibledoctor_freeze/',
'ln -sfn /var/www/virtual/geeklab/html/ansibledoctor_freeze /var/www/virtual/geeklab/ansible-doctor.geekdocs.de',
],
username: { from_secret: 'ssh_username' },
},
},
{
name: 'publish',
image: 'appleboy/drone-scp',
settings: {
host: { from_secret: 'ssh_host' },
key: { from_secret: 'ssh_key' },
rm: true,
source: 'docs/public/*',
strip_components: 2,
target: '/var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de/',
username: { from_secret: 'ssh_username' },
},
},
{
name: 'cleanup',
image: 'appleboy/drone-ssh',
settings: {
host: { from_secret: 'ssh_host' },
key: { from_secret: 'ssh_key' },
script: [
'ln -sfn /var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de /var/www/virtual/geeklab/ansible-doctor.geekdocs.de',
'rm -rf /var/www/virtual/geeklab/html/ansibledoctor_freeze/',
],
username: { from_secret: 'ssh_username' },
},
},
],
depends_on: [
'build-package',
'build-container-amd64',
'build-container-arm64',
'build-container-arm',
],
trigger: {
ref: ['refs/heads/master', 'refs/tags/**'],
},
};
local PipelineNotifications = {
kind: "pipeline",
name: "notifications",
kind: 'pipeline',
name: 'notifications',
platform: {
os: "linux",
arch: "amd64",
os: 'linux',
arch: 'amd64',
},
steps: [
{
image: "plugins/manifest",
name: "manifest",
pull: "always",
image: 'plugins/manifest',
name: 'manifest',
settings: {
ignore_missing: true,
auto_tag: true,
username: { from_secret: "docker_username" },
password: { from_secret: "docker_password" },
spec: "manifest.tmpl",
},
when: {
ref: [
'refs/heads/master',
'refs/tags/**',
],
username: { from_secret: 'docker_username' },
password: { from_secret: 'docker_password' },
spec: 'manifest.tmpl',
},
},
{
name: "readme",
image: "sheogorath/readme-to-dockerhub",
pull: "always",
name: 'readme',
image: 'sheogorath/readme-to-dockerhub',
environment: {
DOCKERHUB_USERNAME: { from_secret: "docker_username" },
DOCKERHUB_PASSWORD: { from_secret: "docker_password" },
DOCKERHUB_REPO_PREFIX: "xoxys",
DOCKERHUB_REPO_NAME: "ansible-doctor",
README_PATH: "README.md",
SHORT_DESCRIPTION: "ansible-doctor - Simple annotation based documentation for your roles"
},
when: {
ref: [
'refs/heads/master',
'refs/tags/**',
],
DOCKERHUB_USERNAME: { from_secret: 'docker_username' },
DOCKERHUB_PASSWORD: { from_secret: 'docker_password' },
DOCKERHUB_REPO_PREFIX: 'xoxys',
DOCKERHUB_REPO_NAME: 'ansible-doctor',
README_PATH: 'README.md',
SHORT_DESCRIPTION: 'ansible-doctor - Simple annotation based documentation for your roles',
},
},
{
name: "microbadger",
image: "plugins/webhook",
pull: "always",
name: 'microbadger',
image: 'plugins/webhook',
settings: {
urls: { from_secret: "microbadger_url" },
urls: { from_secret: 'microbadger_url' },
},
},
{
name: "matrix",
image: "plugins/matrix",
name: 'matrix',
image: 'plugins/matrix',
settings: {
template: "Status: **{{ build.status }}**<br/> Build: [{{ repo.Owner }}/{{ repo.Name }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}<br/> Message: {{ build.message }}",
roomid: { "from_secret": "matrix_roomid" },
homeserver: { "from_secret": "matrix_homeserver" },
username: { "from_secret": "matrix_username" },
password: { "from_secret": "matrix_password" },
homeserver: { from_secret: 'matrix_homeserver' },
roomid: { from_secret: 'matrix_roomid' },
template: 'Status: **{{ build.status }}**<br/> Build: [{{ repo.Owner }}/{{ repo.Name }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}<br/> Message: {{ build.message }}',
username: { from_secret: 'matrix_username' },
password: { from_secret: 'matrix_password' },
},
},
],
depends_on: [
"build-package",
"build-container-amd64",
"build-container-arm64",
"build-container-arm"
'docs',
],
trigger: {
ref: ["refs/heads/master", "refs/tags/**"],
status: [ "success", "failure" ],
ref: ['refs/heads/master', 'refs/tags/**'],
status: ['success', 'failure'],
},
};
[
PipelineLint,
PipelineTest,
PipelineSecurity,
PipelineBuildPackage,
PipelineBuildContainer(arch="amd64"),
PipelineBuildContainer(arch="arm64"),
PipelineBuildContainer(arch="arm"),
PipelineNotifications,
PipelineLint,
PipelineTest,
PipelineSecurity,
PipelineBuildPackage,
PipelineBuildContainer(arch='amd64'),
PipelineBuildContainer(arch='arm64'),
PipelineBuildContainer(arch='arm'),
PipelineDocs,
PipelineNotifications,
]

163
.drone.yml
View File

@ -8,7 +8,6 @@ platform:
steps:
- name: flake8
pull: always
image: python:3.7
commands:
- pip install -r test-requirements.txt -qq
@ -20,8 +19,8 @@ steps:
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
---
kind: pipeline
@ -33,7 +32,6 @@ platform:
steps:
- name: python35-pytest
pull: always
image: python:3.5
commands:
- pip install -r test-requirements.txt -qq
@ -45,7 +43,6 @@ steps:
- clone
- name: python36-pytest
pull: always
image: python:3.6
commands:
- pip install -r test-requirements.txt -qq
@ -57,7 +54,6 @@ steps:
- clone
- name: python37-pytest
pull: always
image: python:3.7
commands:
- pip install -r test-requirements.txt -qq
@ -69,7 +65,6 @@ steps:
- clone
- name: python38-rc-pytest
pull: always
image: python:3.8-rc
commands:
- pip install -r test-requirements.txt -qq
@ -83,8 +78,8 @@ steps:
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- lint
@ -99,7 +94,6 @@ platform:
steps:
- name: bandit
pull: always
image: python:3.7
commands:
- pip install -r test-requirements.txt -qq
@ -111,8 +105,8 @@ steps:
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- test
@ -127,35 +121,31 @@ platform:
steps:
- name: build
pull: always
image: python:3.7
commands:
- python setup.py sdist bdist_wheel
- name: checksum
pull: always
image: alpine
commands:
- "cd dist/ && sha256sum * > ../sha256sum.txt"
- cd dist/ && sha256sum * > ../sha256sum.txt
- name: publish-github
pull: always
image: plugins/github-release
settings:
api_key:
from_secret: github_token
files:
- "dist/*"
- dist/*
- sha256sum.txt
note: CHANGELOG.md
overwrite: true
title: "${DRONE_TAG}"
title: ${DRONE_TAG}
when:
ref:
- "refs/tags/**"
- refs/tags/**
- name: publish-pypi
pull: always
image: plugins/pypi
settings:
password:
@ -166,13 +156,13 @@ steps:
from_secret: pypi_username
when:
ref:
- "refs/tags/**"
- refs/tags/**
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- security
@ -187,13 +177,11 @@ platform:
steps:
- name: build
pull: always
image: python:3.7
commands:
- python setup.py bdist_wheel
- name: dryrun
pull: always
image: plugins/docker:18-linux-amd64
settings:
dockerfile: Dockerfile
@ -205,10 +193,9 @@ steps:
from_secret: docker_username
when:
ref:
- "refs/pull/**"
- refs/pull/**
- name: publish
pull: always
image: plugins/docker:18-linux-amd64
settings:
auto_tag: true
@ -222,13 +209,13 @@ steps:
when:
ref:
- refs/heads/master
- "refs/tags/**"
- refs/tags/**
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- security
@ -243,13 +230,11 @@ platform:
steps:
- name: build
pull: always
image: python:3.7
commands:
- python setup.py bdist_wheel
- name: dryrun
pull: always
image: plugins/docker:18-linux-arm64
settings:
dockerfile: Dockerfile
@ -261,10 +246,9 @@ steps:
from_secret: docker_username
when:
ref:
- "refs/pull/**"
- refs/pull/**
- name: publish
pull: always
image: plugins/docker:18-linux-arm64
settings:
auto_tag: true
@ -278,13 +262,13 @@ steps:
when:
ref:
- refs/heads/master
- "refs/tags/**"
- refs/tags/**
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- security
@ -299,13 +283,11 @@ platform:
steps:
- name: build
pull: always
image: python:3.7
commands:
- python setup.py bdist_wheel
- name: dryrun
pull: always
image: plugins/docker:18-linux-arm
settings:
dockerfile: Dockerfile
@ -317,10 +299,9 @@ steps:
from_secret: docker_username
when:
ref:
- "refs/pull/**"
- refs/pull/**
- name: publish
pull: always
image: plugins/docker:18-linux-arm
settings:
auto_tag: true
@ -334,17 +315,91 @@ steps:
when:
ref:
- refs/heads/master
- "refs/tags/**"
- refs/tags/**
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- "refs/pull/**"
- refs/tags/**
- refs/pull/**
depends_on:
- security
---
kind: pipeline
name: docs
platform:
os: linux
arch: amd64
concurrency:
limit: 1
steps:
- 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
image: klakegg/hugo:0.59.1-ext-alpine
commands:
- cd docs/ && hugo-official
- name: freeze
image: appleboy/drone-ssh
settings:
host:
from_secret: ssh_host
key:
from_secret: ssh_key
script:
- cp -R /var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de/ /var/www/virtual/geeklab/html/ansibledoctor_freeze/
- ln -sfn /var/www/virtual/geeklab/html/ansibledoctor_freeze /var/www/virtual/geeklab/ansible-doctor.geekdocs.de
username:
from_secret: ssh_username
- name: publish
image: appleboy/drone-scp
settings:
host:
from_secret: ssh_host
key:
from_secret: ssh_key
rm: true
source: docs/public/*
strip_components: 2
target: /var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de/
username:
from_secret: ssh_username
- name: cleanup
image: appleboy/drone-ssh
settings:
host:
from_secret: ssh_host
key:
from_secret: ssh_key
script:
- ln -sfn /var/www/virtual/geeklab/html/ansible-doctor.geekdocs.de /var/www/virtual/geeklab/ansible-doctor.geekdocs.de
- rm -rf /var/www/virtual/geeklab/html/ansibledoctor_freeze/
username:
from_secret: ssh_username
trigger:
ref:
- refs/heads/master
- refs/tags/**
depends_on:
- build-package
- build-container-amd64
- build-container-arm64
- build-container-arm
---
kind: pipeline
name: notifications
@ -355,7 +410,6 @@ platform:
steps:
- name: manifest
pull: always
image: plugins/manifest
settings:
auto_tag: true
@ -365,13 +419,8 @@ steps:
spec: manifest.tmpl
username:
from_secret: docker_username
when:
ref:
- refs/heads/master
- "refs/tags/**"
- name: readme
pull: always
image: sheogorath/readme-to-dockerhub
environment:
DOCKERHUB_PASSWORD:
@ -382,13 +431,8 @@ steps:
from_secret: docker_username
README_PATH: README.md
SHORT_DESCRIPTION: ansible-doctor - Simple annotation based documentation for your roles
when:
ref:
- refs/heads/master
- "refs/tags/**"
- name: microbadger
pull: always
image: plugins/webhook
settings:
urls:
@ -410,19 +454,16 @@ steps:
trigger:
ref:
- refs/heads/master
- "refs/tags/**"
- refs/tags/**
status:
- success
- failure
depends_on:
- build-package
- build-container-amd64
- build-container-arm64
- build-container-arm
- docs
---
kind: signature
hmac: 24cc5ebb0319158e48a67f6433b0712b02ed5e50cd7fcb3ec0a9651d0e0d6c6a
hmac: effd4a9b4d0a8672e91c75931a015e4ae4d343678d408c5061f9009b00d859ae
...

5
.gitignore vendored
View File

@ -101,3 +101,8 @@ env*/
.pytest_cache
pip-wheel-metadata
# Hugo documentation
docs/themes/
docs/public/
resources/_gen/

28
docs/config.yaml Normal file
View File

@ -0,0 +1,28 @@
---
baseURL: https://ansible-doctor.geekdocs.de/
title: ansible-doctor
theme: hugo-geekdoc
pygmentsUseClasses: true
pygmentsCodeFences: true
# Geekdoc configuration
disablePathToLower: true
enableGitInfo: true
# Needed for mermaid/katex shortcodes
markup:
goldmark:
renderer:
unsafe: true
tableOfContents:
startLevel: 1
params:
geekdocMenuBundle: true
geekdocToC: 3
geekdocRepo: https://github.com/xoxys/ansible-doctor
geekdocEditPath: edit/master/docs/content
geekdocDateFormat: "Jan 2, 2006"
geekdocSearch: true

17
docs/content/_index.md Normal file
View File

@ -0,0 +1,17 @@
---
title: Documentation
---
[![Build Status](https://cloud.drone.io/api/badges/xoxys/ansible-doctor/status.svg)](https://cloud.drone.io/xoxys/ansible-doctor)
[![](https://img.shields.io/pypi/pyversions/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/)
[![](https://img.shields.io/pypi/status/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/)
[![](https://img.shields.io/pypi/v/ansible-doctor.svg)](https://pypi.org/project/ansible-doctor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](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 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).
You can find the full documentation at [ansible-doctor.geekdocs.de](https://ansible-doctor.geekdocs.de).

13
docs/content/configuration/_index.md Normal file
View File

@ -0,0 +1,13 @@
---
title: 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

29
docs/content/configuration/cli.md Normal file
View File

@ -0,0 +1,29 @@
---
title: CLI options
---
You can get all available cli options by running `ansible-later --help`:
{{< highlight Shell "linenos=table" >}}
$ 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
{{< /highlight >}}

36
docs/content/configuration/defaults.md Normal file
View File

@ -0,0 +1,36 @@
---
title: Default settings
---
{{< highlight YAML "linenos=table" >}}
---
# 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
{{< /highlight >}}

18
docs/content/configuration/env.md Normal file
View File

@ -0,0 +1,18 @@
---
title: Environment Variables
---
{{< highlight Shell "linenos=table" >}}
ANSIBLE_DOCTOR_CONFIG_FILE=
ANSIBLE_DOCTOR_ROLE_DIR=
ANSIBLE_DOCTOR_DRY_RUN=false
ANSIBLE_DOCTOR_LOG_LEVEL=warning
ANSIBLE_DOCTOR_LOG_JSON=false
ANSIBLE_DOCTOR_OUTPUT_DIR=
ANSIBLE_DOCTOR_TEMPLATE_DIR=
ANSIBLE_DOCTOR_TEMPLATE=readme
ANSIBLE_DOCTOR_FORCE_OVERWRITE=false
ANSIBLE_DOCTOR_CUSTOM_HEADER=
ANSIBLE_DOCTOR_EXCLUDE_FILES=
ANSIBLE_DOCTOR_EXCLUDE_FILES=molecule/,files/**/*.py
{{< /highlight >}}

4
docs/content/setup/_index.md Normal file
View File

@ -0,0 +1,4 @@
---
title: Setup
---

22
docs/content/setup/docker.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Using docker
---
{{< highlight Shell "linenos=table" >}}
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
{{< /highlight >}}
{{< 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.
{{< /hint >}}

15
docs/content/setup/pip.md Normal file
View File

@ -0,0 +1,15 @@
---
title: Using pip
---
{{< highlight Shell "linenos=table" >}}
# 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
{{< /highlight >}}

35
docs/content/usage/_index.md Normal file
View File

@ -0,0 +1,35 @@
---
title: 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.
{{< highlight Yaml "linenos=table" >}}
# @identifier option1:option2: <value>
# @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"
{{< /highlight >}}
These list of pre-defined identifiers is currently available:
* @meta
* @todo
* @var
* @tag

19
docs/data/menu/main.yml Normal file
View File

@ -0,0 +1,19 @@
---
main:
- name: Setup
sub:
- name: Using pip
ref: "/setup/pip"
- name: Using docker
ref: "/setup/docker"
- name: Configuration
ref: "/configuration"
sub:
- name: Default settings
ref: "/configuration/defaults"
- name: CLI options
ref: "/configuration/cli"
- name: Environment variables
ref: "/configuration/env"
- name: Usage
ref: "/usage"

10
docs/data/menu/more.yml Normal file
View File

@ -0,0 +1,10 @@
---
more:
- name: Releases
ref: "https://github.com/xoxys/ansible-doctor/releases"
external: true
icon: "download"
- name: "View Source"
ref: "https://github.com/xoxys/ansible-doctor"
external: true
icon: "github"