Currently in Migration - Jason Edelman's Old Blog
  • Home
  • About
  • Contact

Generating Web Docs for Ansible Modules

2/15/2015

0 Comments

 
If you have ever worked with Ansible, it’s almost a guarantee that you have used their online docs to figure out what parameters a given module supports, how they should be used, or what their defaults are.  Over the past few weeks, I’ve been working on a few custom modules and was trying to find a way to generate web docs for them, and have them locally accessible or easily posted to GitHub.  
Ansible offers a way to “make webdocs,” but it generates the complete module inventory and truth be told, I didn’t get this work for my custom modules, so I figured I would explore a “simplified” way --- a way that should be able to generate docs as needed for one or more modules on an as needed basis.  

The outcome was the creation of an Ansible module and Jinja2 template that automatically generates a markdown file (that can then be viewed or posted anywhere). 

How does it work?

The modules you’ve built or are local to your machine (even Ansible core modules) that you want to generate a web doc for must be documented according to Ansible standards.  That’s the only major requirement.

From there, you create a playbook that’ll generate the required markdown document. 

Here is a sample playbook that generates a markdown doc for the Ansible files modules.
Picture
There are three main areas to cover about this playbook.  (1) vars (2) obtaining the docs and (3) creating the markdown file.

Three variables can optionally be defined (heading, subheading, and requirements) that would then be displayed when the markdown doc is generated.

The first task uses the new custom module called ansible_docstring.  This module gathers the appropriate module documentation and examples from all modules in a given directory.  These docs and examples are then stored in a new variable called modules.

The second task then generates the final markdown doc based on the new Jinja2 template.

In order to get started, just make sure you have Ansible installed, do a git clone of the repo, and execute the playbook.  You’ll then need a way of viewing the markdown file in a web browser if you aren’t using GitHub.

Sound easy enough?

Below are a few screen shots of what the playbook generates.  To see the actual thing, check it out here.

Sample 1
Picture
Sample 2
Picture
Sample 3
Picture
Because my blog platform lacks significant features, I can’t post the markdown or full output here.  To see the full detail, check it out on GitHub.
Note: it’s not shown in this post, but the playbook is generating a markdown file and then I was previewing the markdown in HTML using a markdown viewer plugin for Sublime Text 3.  Following that, I then just uploaded the created markdown file to GitHub.
Since everything has been posted to GitHub, feel free to download the example playbook, template, and the ansible_docstring module to try it out.  There are likely some error checks that could be improved, so if you want to contribute, open an issue or pull request!

On a side note, if I didn't end up creating this, I would have spent a ton of time manually creating tables in markdown one at a time for each module I was building!  And just imagine making a small change like adding a row or column to each one!  

Happy Documenting!

Thanks,
Jason

Twitter: @jedelman8
0 Comments



Leave a Reply.

    Author

    Jason Edelman, Founder of Network to Code, focused on training and services for emerging network technologies. CCIE 15394.  VCDX-NV 167.


    Enter your email address:

    Delivered by FeedBurner


    Top Posts

    The Future of Networking and the Network Engineer

    OpenFlow, vPath, and SDN

    Network Virtualization vs. SDN

    Nexus 7000 FAQ

    Possibilities of OpenFlow/SDN Applications 

    Loved, Hated, but Never Ignored #OpenFlow #SDN

    Software Defined Networking: Cisco Domination to Market Education

    OpenFlow, SDN, and Meraki

    CAPWAP and OpenFlow - thinking outside the box

    Introduction to OpenFlow...for Network Engineers


    Categories

    All
    1cloudroad
    2011
    2960
    40gbe
    7000
    Arista
    Aruba
    Big Switch
    Brocade
    Capwap
    Christmas
    Cisco
    Controller
    Data Center
    Dell Force10
    Embrane
    Extreme
    Fex
    Hadoop
    Hp
    Ibm
    Isr G2
    Juniper
    Limited Lifetime Warranty
    Meraki
    Multicast
    N7k
    Nexus
    Nicira
    Ons
    Opendaylight
    Openflow
    Openstack
    Presidio
    Qsfp
    Quick Facts
    Routeflow
    Sdn
    Sdn Ecosystem
    Security
    Ucs


    Archives

    May 2015
    April 2015
    February 2015
    January 2015
    December 2014
    November 2014
    October 2014
    September 2014
    August 2014
    June 2014
    May 2014
    March 2014
    February 2014
    January 2014
    December 2013
    November 2013
    October 2013
    September 2013
    August 2013
    July 2013
    June 2013
    May 2013
    April 2013
    March 2013
    February 2013
    January 2013
    December 2012
    November 2012
    October 2012
    June 2012
    May 2012
    April 2012
    March 2012
    February 2012
    January 2012
    December 2011
    November 2011


    RSS Feed


    View my profile on LinkedIn
Photo used under Creative Commons from NASA Goddard Photo and Video