ansigenome 0.1.1

A tool designed to help you manage your Ansible roles.

Ansigenome

Ansigenome is a command line tool designed to help you manage your Ansible roles. It does 6 things:

• scan a path containing Ansible roles and report back useful stats

• rebuild a path of roles which auto generates a README.md and meta/main.yml from templates

• run shell commands inside of each role’s directory

• init new roles with a travis-ci test already made for you

• export a path of roles to a file to be consumed by ansible-galaxy install -r

• dump a json file containing every stat it gathers from a directory

A screenshot speaks a thousand words:

Installation

If you have Ansible installed then you already have all of the dependencies you need to run Ansigenome. You have 2 options for installation:

pip install ansigenome or easy_install ansigenome

Ansible installed setup tools so you should already have easy_install. You may need to use sudo if you get permission errors.

Usage

The help is setup similar to Ansible’s command line tools. Your best bet is to just type ansigenome in a terminal to get a list of commands and explore the options.

Usage: ansigenome [scan|rebuild|run|init|export|dump] [--help] [options]


ansigenome scan --help
scan a path containing Ansible roles and report back useful stats

ansigenome rebuild --help
rebuild a path of roles which auto generates a `README.md` and `meta/main.yml` from templates

ansigenome run --help
run shell commands inside of each role's directory

ansigenome init --help
init new roles with a travis-ci test already made for you

ansigenome export --help
export a path of roles to a file to be consumed by ansible-galaxy install -r

ansigenome dump --help
dump a json file containing every stat it gathers from a directory


Options:
  -h, --help  show this help message and exit

'ansigenome command --help' for more information on a specific command

Stats gathered

Here are the stats gathered which could be dumped to json if you wish.

report = {
    "totals": {
        "roles": 0,
        "dependencies" 0,
        "defaults": 0,
        "facts": 0,
        "files": 0,
        "lines": 0,
    },
    "roles": {
        # All of the stats below get harvested from each role you scan.
        %role_name: {
            "total_dependencies": 0
            "total_defaults": 0,
            "total_facts": 0,
            "total_lines": 0,
            "total_files": 0,
            "facts": [],
            "dependencies": {},
            "defaults": [],
            "meta": {},
            "readme": "",
        }
    },
    "stats": {
        "longest_role_name_length": 0
    }
}

Templates

You might decide that the default templates don’t suite your style. That’s completely reasonable. You can supply your own readme and meta templates.

You can either provide a url to the template on the command line or a path to the template when you run the rebuild command.

README.md.j2

Here are all of the values you have access to in the template if you decide to make your own custom readme template. Check templates/README.md.j2 for an example.

# The username supplied by the -u flag in Ansigenome.
github_username: "%github_username"

# The repo name supplied by Ansigenome.
repo_name: "%repo_name"

# The full role name in the galaxy format supplied by Ansigenome.
galaxy_name: "%galaxy_name"

# ============================================================================
# You also have access to everything in the meta/main.yml.j2 template.
# Look below in the meta/main.yml.j2 section to see a list of values.
# ============================================================================

meta/main.yml.j2

Here are all of the values you have access to in the template if you decide to make your own custom meta template. Check templates/meta/main.yml.j2 for an example.

# Populated with the author's name or Your name if it can't find it.
galaxy_info.author: "Your name"

# A short 1 liner which appears on the galaxy.
galaxy_info.description: "A short description of your role."

# The company that this role belongs to.
galaxy_info.company: ""

# The license.
galaxy_info.license: "MIT"

# The minimum version of Ansible for this role.
galaxy_info.min_ansible_version: 1.6

# The platforms that this role supports.
galaxy_info.platforms:
  - name: Ubuntu
    versions:
    - precise
  - name: Debian
    versions:
    - wheezy

# ----------------------------------------------------------------------------

# A list of any dependencies for this role.
dependencies: []

# ----------------------------------------------------------------------------

# An extension to the meta file to hold this role's custom data.
meta_info: {}

# Describe the goal of your project, this appears at the top of the readme.
meta_info.synopsis: "It is an ansible role that ..."

# The full github url to where your role is hosted.
meta_info.github_url: "https://github.com/%github_username/%repo_name"

# The git branch to use.
meta_info_git_branch: "master"

# The role id to find your role on Ansible's galaxy.
meta_info.galaxy_id: ""

# Add a getting started guide to your readme.
# It should be the bare minimum to get going with your role.
meta_info.inventory: ""

# Overwrite the generated defaults with custom text.
meta_info.defaults: ""

# Overwrite the generated facts with custom text.
meta_info.facts: ""

# Add anything you want under the facts.
meta_info.custom: ""

# Any extra text you would like to add at the very bottom of the readme.
meta_info.footer: ""

Contributing

If you would like to contribute then check out Ansible’s contribution guide because this project expects the same requirements and it contains great tips on using git branches.

In addition to that your code must pass the default pep8 style guide. I have travis running a test to ensure the code follows that guide but your best bet is to find a plugin for your editor if you don’t have one already.

License

GPLv3

Author

Ansigenome was created by Nick Janetakis [e-mail].

Special thanks to @drybjed for coming up with the name of the tool. This project idea spawned from trying to break up his ginas project into multiple roles. Neither of us wanted to manually make 50 repos and 50 readmes so I decided to learn Python and make this tool instead.