ansidoc 0.6.0
Manage ansible role documentation
License: MIT
Keywords: ansible,documentation generation


Ansidoc
=======

A simple tool to generate ansible role's documentation.

Usage
-----

This tool generates a ``README.md`` file using data from multiple sources.


* From role content:

  * role ``defaults/main.yml``
  * role ``vars/*.yml``

* You content.

  * role ``docs/*.yml``
  * role ``docs/*.md``

Content of your role ``vars/*`` and ``defaults/*`` will also be literally inserted
in between ``yaml`` codeblocks. Put nice comments//explanations of variable's
purpose in them!

The role ``docs`` directory may contain YAML files that will be parsed. Variables
within will be use to enrich the resulting ``README.md`` file. All markdown files
will also be include. Top header must be of level H2. Currently there are no
mechanism to defined the inclusion order.

Prepare your role
^^^^^^^^^^^^^^^^^

For best results, create a ``docs/<you-var-file>.yml`` file inside your role and fill those
variables:

.. code-block:: yaml

   ---

   github_account: <your-role-github-account-username>
   todos: [] # (optional) list of todos to print in your README file

cli
^^^

.. code-block:: shell

   usage: ansidoc [-h] [-v] [-V] [-d] [-s TARGET] [-nf] [-e EXCLUDE] [-p] dirpath

   positional arguments:
     dirpath               Either a 'roles_path' wich is a roles' directory or a
                           path to a single role. If 'roles_path' basename is
                           'roles' it will loop over subdirectories assuming each
                           of them contains a role.

   optional arguments:
     -h, --help            show this help message and exit
     -v, --verbose         increase output verbosity
     -V, --version         show program's version number and exit
     -d, --dry-run         dry run, Outputs pure markdown to stdout nothing is
                           written to disk
     -s TARGET             (docs | README.md) Create a symlink in PWD to TARGET.
                           This is useful when used from sphinx as you cannot add
                           relative entries such as '../*' in the toctree. If
                           unspecified, no symlink is created.
     -nf, --no-ansidoc-footer
                           Do not render the ansidoc project footer.
     -e EXCLUDE, --exclude EXCLUDE
                           csv list of role names to exclude. Must match
                           directory name found under specified 'dirpath'
     -p, --private         Consider role(s) private, e.g.: Skip installation from
                           github part from rendered template.

>From sphinx
^^^^^^^^^^^

You can import in your code and pass arguments similarly as you would do on the
cli.

For example:

.. code-block:: python

   from ansidoc import Ansidoc
   ansidoc = Ansidoc(dirpath=<path/to/role>, dry_run=True)
   ansidoc.run()

wishlist
--------


* role dependency grapher
* role variables analysis (to audit what is defined where)
* create sphinx documentation for this program
* make this a sphinx plugin
* include mardown files in defined order (alphabetical?, number the files?)
* override parts of template with custom one.

  * search paths to find templates (\ ``.ansidoc/templates/*``\ ?)

* multi-role variables

  * search paths to find config (\ ``.ansidoc/config.yml``\ ?)
  * exclude list configurable in config file

License
-------

MIT.

Similar Projects
----------------


* `Ansible-DocGen <https://github.com/toast38coza/Ansible-DocGen>`_