A tool to help you gather information and manage your Ansible roles.
|PyPI version| |Build status|
Ansigenome is a command line tool designed to help you manage your Ansible roles.
Scan your roles and organize your documentation
.. figure:: https://raw.githubusercontent.com/nickjj/ansigenome/master/docs/ansigenome-scan.png :alt: Ansigenome scan screenshot
Create dependency graphs in seconds
.. figure:: https://raw.githubusercontent.com/nickjj/ansigenome/master/docs/ansigenome-graph.png :alt: Ansigenome graph of DebOps
Generated from the
DebOps_ project.
...and more!
Table of contents ~~~~~~~~~~~~~~~~~
Use case_
Installation_
Quick start_
Template variables_
Contributing_
Author_
Use case ~~~~~~~~
Are 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 roles_
Standardize your readmes in an automated way_
Augment existing meta files_
Export graphs and requirements files_
Create brand new roles_
Run shell commands in the context of each role_
Gather metrics on your roles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Just run
ansigenome scanat a path containing all of your roles or
ansigenome scan /path/to/rolesand it will gather stats such as:
Will 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 way ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
When 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 as
scanexcept it will read your
meta/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 it will overwrite your existing readme file for 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 the
DebOps 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 files ~~~~~~~~~~~~~~~~~~~~~~~~~~~
You 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 before
ansigenome gendoc. After running
genmetayou will be able to take your old readme files and move some of it to the new meta file that
genmetamade for you.
Will it change my roles? ````````````````````````
It will rewrite your meta file for each role but it will not mess with your formatting. It will only augment a few fields that are missing and overwrite things like the
galaxy_info.companyname with what you supplied in the Ansigenome config (more on this later, we're almost there).
Export graphs and requirements files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Graphs ``````
Just run
ansigenome export -oand 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
-f dotso you can pipe it to a different Graphviz graphing utility.
Requirements files ``````````````````
Have a go with
ansigenome export -t reqs -oto generate a file for consumption by
ansible-galaxy install -r. It also supports the
-f ymlflag to use the new yaml format.
JSON dump `````````
You can also dump everything Ansigenome gathered to json by running
ansigenome export -t dump -o.
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 roles ~~~~~~~~~~~~~~~~~~~~~~
Everyone loves making new roles right? Well,
ansigenome initwill do just that for you. What's different from using
ansible-galaxy init? Here, I'll tell you:
tests/directory and
.travis.ymlfile for you automatically
It uses a tool called
Rolespec_ for 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 role ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes 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 the
foofile in the root directory of each role.
Installation ~~~~~~~~~~~~
If 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 develop
Quick start ~~~~~~~~~~~
So Ansigenome is installed, well done. Just run
ansigenome 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 command
Tips ````
Do not forget to check out the
--helpfor each command
Learn how jinja2 extends works, you can use it for the readme template
{% extends "README.md.j2" %}
gendocaccepts
-f mdto generate markdown readmes instead of rst
scan,
gendoc,
genmetaand
rundon't require a roles path
$PWD/playbooks/rolesthen
$PWD
You can write a config out to a custom path with
-o
The
export -t reqscommand accepts a
-vflag to read in a VERSION file
The
initcommand accepts a
-cflag
scan,
gendoc,
genmeta,
runand
dumpaccept an
-lflag
If you are the only author you do not need to specify
ansigenome_info.authors
Template variables ~~~~~~~~~~~~~~~~~~
Here'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.githubAccess 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 author
You can find many meta example files at the
DebOps project_ page.
Custom readme template ``````````````````````
You 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" %}
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.
Author ~~~~~~
Ansigenome was created by Nick Janetakis [email protected]
Special thanks to
@drybjed_ for coming up with the name of the tool. This project idea spawned from trying to break up the
DebOps 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.
License ~~~~~~~
GPLv3_
.. |PyPI version| image:: https://badge.fury.io/py/ansigenome.png :target: https://pypi.python.org/pypi/ansigenome .. |Build status| image:: https://secure.travis-ci.org/nickjj/ansigenome.png :target: https://travis-ci.org/nickjj/ansigenome