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.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

ansidoc-0.6.0-py3-none-any.whl (13.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page