Documentation generated from comments in Ansible YML files, tweaked for compatibility with @appnest/readme

Table of Contents

• Overview
• Custom Titles
• Variables' Title Prefix, Postfix and Example Comment Prefix
  • sdk_location
• Installation
  • PyPi
  • Install Doctor
  • Homebrew
  • Chocolatey
  • Binary Releases
• Requirements
• Contributing
• License

Overview

ansible-autodoc is a documentation tool that generates documentation from comments in Ansible source files (i.e. YML files). mod-ansible-autodoc is a fork of ansible-autodoc that fixes a few issues. It also changes some of the data output formats to play nice with @appnest/readme.

Custom Titles

There are 4 optional args for this, one per markdown file:

1. --todo-title
2. --actions-title
3. --tags-title
4. --variables-title

The value of an argument has to be wrapped around ''. Example:

mod-ansible-autodoc --todo-title '## IMPROVEMENTS FILE'

Variables' Title Prefix, Postfix and Example Comment Prefix

It's possible to add a prefix and/or postfix to ansible_variables.md's subheaders and a prefix to the example comment. Simply run:

mod-ansible-autodoc --variable-title-prefix '###' --variable-title-postfix ' <!-- VARIABLE_FIX -->' --variable-example-comment-prefix '##PREFIX##'

Then, expect something like the following:

### `sdk_location` <!-- VARIABLE_FIX -->

yaml
##PREFIX## Example implementation of the sdk_location variable
sdk_location: ~/Android/Sdk

Installation

To accomodate everyone, this CLI can be installed using a variety of methods.

PyPi

If you already have Python 3 and pip3 installed, you can install the CLI by running:

pip3 install {{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}

Install Doctor

On macOS or Linux, you can run:

bash -sS https://install.doctor/py/{{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}

And on Windows, you can run:

Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://install.doctor/py/{{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}?os=win'))

Homebrew

If you have Homebrew installed, you can install the package by running:

brew install installdoc/py/{{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}

Or if you prefer to keep Python off your system, and install a binary, you can run:

brew install installdoc/py/{{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}-binary

Chocolatey

If you are on Windows, you can install a binary version (without the Python dependency), using Chocolatey:

choco install {{(if customPyPiPackageName customPyPiPackageName (append repository.prefix.github slug))}}

Binary Releases

There are also binaries (in various formats) available for download on both GitHub and GitLab.

Requirements

To run this project, all you need is Python 3 and pip3. See the Installation section for instructions that include alternate installation methods that do not require Python to be installed.

If you are interested in contributing or would like to make some modifications, please see the CONTRIBUTING guide. There are a handful of build tools we incorporate into the development process. All of them are installed automatically via our Taskfile system. You can get started customizing this project by running:

bash .config/scripts/start.sh
task start
task --list

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page. If you would like to contribute, please take a look at the contributing guide.

Brian Zalewski

License

Copyright © 2020-2021 Megabyte LLC. This project is MIT licensed.