Package: ansigenome
AnsigenomeAnsigenome is a command line tool designed to help you manage your Ansible roles.Scan your roles and organize your documentationCreate dependency graphs in secondsGenerated from theDebOpsproject.…and more!Table of contentsUse caseInstallationQuick startTemplate variablesContributingAuthorUse caseAre you someone with 1 or 100+ roles? Then you will benefit from using Ansigenome, let’s go over what Ansigenome can do for you:Gather metrics on your rolesStandardize your readmes in an automated wayAugment existing meta filesExport graphs and requirements filesCreate brand new rolesRun shell commands in the context of each roleGather metrics on your rolesJust runansigenome scanat a path containing all of your roles oransigenome scan /path/to/rolesand it will gather stats such as:Number of defaults, facts, files and lines found in each role and total themVerify if you’re missing meta or readme filesWill it change my roles?Nope. This command is completely read only. All of your custom formatting and content is safe.Standardize your readmes in an automated wayWhen I started to get to about 5 roles I dreaded making readmes for each one because there’s so much boilerplate and duplication. We’re programmers, so let’s use tools to help us.ansigenome gendocwill do the same asscanexcept it will read yourmeta/main.ymlfile and generate a readme based on the stats it found and also format your readme based on a jinja2 template.It can generate both RST and MD readmes.You can use the default template or optionally supply a custom template using
blocks to customize the entire readme to your liking.Will it change my roles?It will not modify your meta file but itwill overwrite your existing readme filefor each role it’s ran against. You can still add custom info to the readme, but this will be done through the meta file, don’t worry about that just yet.Can I see an example of what it generates?Absolutely. This project sprung out of need while working on theDebOps project. There’s about 60 roles all using an Ansigenome generated readme.All of them were fully generated with 0 manual edits.Augment existing meta filesYou might have 35 roles already written and might want Ansigenome to help you make the adjustment over to using Ansigenome.ansigenome genmetawill take a peek at your meta files for each role, replace certain fields with values you provided to its config (more on this later) and add ansigenome-only fields to that meta file.If you wanted to migrate over to using Ansigenome then this is what you’ll want to run beforeansigenome gendoc. After runninggenmetayou will be able to take your old readme files and move some of it to the new meta file thatgenmetamade for you.Will it change my roles?It will rewrite your meta file for each role but itwill not mess with your formatting. It will only augment a few fields that are missing and overwrite things like thegalaxy_info.companyname with what you supplied in the Ansigenome config (more on this later, we’re almost there).Export graphs and requirements filesGraphsJust runansigenome export-o<path to png output file>and it will use
Graphviz to create a dependency graph.You can also tweak the size and DPI of the graph with a few flags or even
set the output format to be-fdotso you can pipe it to a different
Graphviz graphing utility.Requirements filesHave a go withansigenome export-treqs-o<path to output file>to
generate a file for consumption byansible-galaxyinstall-r<file>. It also supports the-fymlflag to use the new yaml format.JSON dumpYou can also dump everything Ansigenome gathered to json by runningansigenome export-tdump-o<path to output file>.You could then feed that to some database back end or a javascript based graphing utility, etc..Any chance to output to stdout instead of a file?Yes, all of the export commands will output to stdout if you omit the-oflag. The only exception to this is the PNG graph.Will it change my roles?Not at all. It just reads a few files.Create brand new rolesEveryone loves making new roles right? Well,ansigenome init <role name/path>will do just that for you. What’s different from usingansible-galaxyinit? Here, I’ll tell you:Creates an “Ansigenome ready” meta fileCreates atests/directory and.travis.ymlfile for you automaticallyIt uses a tool calledRolespecfor the test code. Don’t worry, you don’t need to download anything.You’ll also never have to write messy Travis configs again but you can still benefit from Travis itself.Will it change my roles?Nah, but it will make a brand new shiny role for you.Run shell commands in the context of each roleSometimes you just want to run a shell command against all of your roles.  Similar to how Ansible lets you run adhoc commands on hosts.ansigenome-m'touch foo'would create thefoofile in the root directory of each role.InstallationIf you have Ansible installed then you already have all of the dependencies you need to run Ansigenome. Pick one of the way below:# Pick an installation method that agrees with you.

pip install ansigenome
easy_install ansigenome

# If you want to live on the edge...

git clone https://github.com/nickjj/ansigenome
cd ansigenome ; sudo python setup.py developQuick startSo Ansigenome is installed, well done. Just runansigenome configand answer a few questions. You only need to do this once.At this point you can run any of the commands below.Usage: ansigenome [config|scan|gendoc|genmeta|export|init|run] [--help] [options]


ansigenome config --help
create a necessary config file to make ansigenome work

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

ansigenome gendoc --help
generate a README from the meta file for each role

ansigenome genmeta --help
augment existing meta files to be compatible with Ansigenome

ansigenome export --help
export roles to a dependency graph, requirements file and more

ansigenome init --help
init new roles with a custom meta file and tests

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


Options:
  --version   show program's version number and exit
  -h, --help  show this help message and exit

ansigenome command --help for more info on a commandTipsDo not forget to check out the--helpfor each commandLearn how jinja2 extends works, you can use it for the readme templateYou’re best off copying the base README and place it next to the custom j2Then you can{% extends "README.md.j2" %}gendocaccepts-fmdto generate markdown readmes instead of rstscan,gendoc,genmetaandrundon’t require a roles pathIt will try$PWD/playbooks/rolesthen$PWDThis allows you to run Ansigenome from your roles path easilyYou can write a config out to a custom path with-o<path>The non-home version of the config will be used if foundFeel free to edit the config file by hand later to change valuesTheexport-treqscommand accepts a-vflag to read in a VERSION fileTheinitcommand accepts a-cflagSupply a comma separated list of Galaxy categoriesscan,gendoc,genmeta,runanddumpaccept an-lflagSupply a comma separated list of roles to white listIf you are the only author you do not need to specifyansigenome_info.authorsTemplate variablesHere’s the available variables you can use in your meta file or optional custom readme template:# Access a single author (taken from your config).
author.name
author.company
author.url
author.email
author.twitter
author.github

# Access all of the authors.
authors

# License.
license.type
license.url

# SCM (source control management).
scm.type
scm.host
scm.user
scm.repo_prefix

# Dynamic items (they are calculated/normalized for you automatically).
role.name
role.galaxy_name
role.slug

# Standard items (you can access any property of these objects).
dependencies
galaxy_info
ansigenome_info

  # ansigenome_info fields.
  galaxy_id   : String based ID to find your role on the Galaxy
  travis      : Boolean to determine if this role is on Travis-CI

  status      : Dictionary with info about the status
     name        : String, currently supported are: beta, deprecated
     note        : String containing additional information about the status

  synopsis    : String block containing what your role does
  usage       : String block containing a detailed usage guide
  custom      : String block containing anything you want

  authors     : List containing information about each authorYou can find many meta example files at theDebOps projectpage.Custom readme templateYou might decide that the current template doesn’t suite your style. That’s completely reasonable. You can supply your own readme template and extend the base one.Just add the path to the custom readme template to your config file. Then copy the base template from this repo to somewhere on your workstation, perhaps next to your custom template.Then in your custom template you can extend it like this:{% extends "README.md.j2" %}

<insert the blocks you want to replace here>Available blocks to replacetitleansigenome_managedbadgesstatusbetadeprecatedsynopsisinstallationdependenciesstandalonedefaultsfactsusageauthorsfooterContributingIf you would like to contribute then check outAnsible’s contribution guidebecause 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.AuthorAnsigenome was created by Nick Janetakisnick.janetakis@gmail.com.Special thanks to@drybjedfor coming up with the name of the tool. This project idea spawned from trying to break up theDebOps projectinto 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.LicenseGPLv3