Skip to main content

Manage ansible role documentation

Project description


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>`_


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
ansidoc-0.6.0-py3-none-any.whl (13.6 kB) Copy SHA256 hash SHA256 Wheel py3

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page