diff --git a/.drone.jsonnet b/.drone.jsonnet index 861faf2..bf6f61c 100644 --- a/.drone.jsonnet +++ b/.drone.jsonnet @@ -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 }}**
Build: [{{ repo.Owner }}/{{ repo.Name }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}
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 }}**
Build: [{{ repo.Owner }}/{{ repo.Name }}]({{ build.link }}) ({{ build.branch }}) by {{ build.author }}
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, ] diff --git a/.drone.yml b/.drone.yml index 835efd9..44fc6d2 100644 --- a/.drone.yml +++ b/.drone.yml @@ -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 ... diff --git a/.gitignore b/.gitignore index 620329a..6f577d7 100644 --- a/.gitignore +++ b/.gitignore @@ -101,3 +101,8 @@ env*/ .pytest_cache pip-wheel-metadata + +# Hugo documentation +docs/themes/ +docs/public/ +resources/_gen/ diff --git a/docs/config.yaml b/docs/config.yaml new file mode 100644 index 0000000..7dce451 --- /dev/null +++ b/docs/config.yaml @@ -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 diff --git a/docs/content/_index.md b/docs/content/_index.md new file mode 100644 index 0000000..296812c --- /dev/null +++ b/docs/content/_index.md @@ -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). diff --git a/docs/content/configuration/_index.md b/docs/content/configuration/_index.md new file mode 100644 index 0000000..109533a --- /dev/null +++ b/docs/content/configuration/_index.md @@ -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 diff --git a/docs/content/configuration/cli.md b/docs/content/configuration/cli.md new file mode 100644 index 0000000..26533f6 --- /dev/null +++ b/docs/content/configuration/cli.md @@ -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 >}} diff --git a/docs/content/configuration/defaults.md b/docs/content/configuration/defaults.md new file mode 100644 index 0000000..ac32d09 --- /dev/null +++ b/docs/content/configuration/defaults.md @@ -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 >}} diff --git a/docs/content/configuration/env.md b/docs/content/configuration/env.md new file mode 100644 index 0000000..5e09eaf --- /dev/null +++ b/docs/content/configuration/env.md @@ -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 >}} diff --git a/docs/content/setup/_index.md b/docs/content/setup/_index.md new file mode 100644 index 0000000..caddedb --- /dev/null +++ b/docs/content/setup/_index.md @@ -0,0 +1,4 @@ +--- +title: Setup + +--- diff --git a/docs/content/setup/docker.md b/docs/content/setup/docker.md new file mode 100644 index 0000000..6cce485 --- /dev/null +++ b/docs/content/setup/docker.md @@ -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 >}} diff --git a/docs/content/setup/pip.md b/docs/content/setup/pip.md new file mode 100644 index 0000000..8b8665a --- /dev/null +++ b/docs/content/setup/pip.md @@ -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 >}} diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md new file mode 100644 index 0000000..ff6439b --- /dev/null +++ b/docs/content/usage/_index.md @@ -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: + +# @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 diff --git a/docs/data/menu/main.yml b/docs/data/menu/main.yml new file mode 100644 index 0000000..da79e25 --- /dev/null +++ b/docs/data/menu/main.yml @@ -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" diff --git a/docs/data/menu/more.yml b/docs/data/menu/more.yml new file mode 100644 index 0000000..6a13a48 --- /dev/null +++ b/docs/data/menu/more.yml @@ -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"