How does the automatic Ansible documentation work?
<p>So this is my situation:
I am writing Ansible playbooks and roles in a huge project directory. Currently my documentation is stored in .md files. But I want to use Ansible's documentation mechanism, so I looked into the sphinx documentation system. It seems pretty neat to me, so I installed it and got into the mechanisms.</p>

<p>But what I cant figure out: How does Ansible include the documentation that is located in the python modules into the sphinx documentation?<br>
I am sorry to be not able to be more specific, but currently I am just scratching the surface I assume.</p>

<p>So here is what I want to achieve:</p>

<ul>
<li>I have the typical <code>roles</code> directory</li>
<li>In it there are several roles</li>
<li>The files are mainly .yaml or .yml files</li>
<li>I at least want to include documentation from one file within these role directories</li>
<li>Ideally I want to pull documentation from several files within the directory</li>
</ul>

<p>If too much is unclear please tell me and I will try to improve the question as I can't figure out for hours how to achieve this or even how to ask precisely.</p>

<p><strong>Thanks in advance for every comment and answer!</strong></p>

<p>Auto doc is only for Ansible modules, not playbooks.<br>
If you want to document your playbooks, you are on your own.<br>
There is a small project on github: <a href="https://github.com/starboarder2001/ansible-docgen" rel="nofollow">ansible-docgen</a> â it fetches a list of tasks into MD files and adds a couple of headers.<br>
You can achive comparable result by calling <code>ansible-playbook --list-tasks myplaybook.yml</code></p>

<p>In my personal opinion, reading playbooks with comments is very convenient.</p>

python documentation ansible yaml python-sphinx