Needs some design work so it looks a little better and not so plain.

Example cli:

-i description,task

attribute would be nice. Make the attributes bold.

Make it so inside of comments you can use jinja2 to do more advanced formatting.

Have base formatter class, basically have separate functions for
write_attribute, write_header, etc functions that can be overridden.
In the baseclass just raise an exception so it has to be implemented.

Expected playbook format:

TESTING ONLY -

• hosts: everything/linux
  tasks:
  • shell: grep test /etc/passwd

Currently it does not parse a playbook because it expects a list, It
should infact expect a dictionary with ["tasks"] being a list.

Hi @starboarder2001 , @nickpack

Found ansible-docgen to be a great tool to document my roles and playbooks. Thanks for building it !

I see that tasks inside ansible block are not added to the documentation. Provided below is a sample playbook and corresponding documentation :

Playbook

# Author: ksatchit
# Description: ansible-docgen issues with block


- hosts: localhost

  tasks:

    - name: First task in the playbook
      shell: echo "PRINT TASK1"

    - block:
        - name: Second task in the playbook, first in the do block
          shell: echo "PRINT TASK2"

      rescue:
        - name: Third task in playbook, first in the rescue block
          shell: echo "PRINT TASK3"

      always:
        - name: Fourth task in playbook, first in the always block
          shell: echo "PRINT TASK4"

README.md

## Playbook: [sampletest.yml](sampletest.yml)
> **Author:** ksatchit

> **Description:** ansible-docgen issues with block

> **Task:** First task in the playbook

The error TypeError: load() missing 1 required positional argument: 'Loader' comes up at running the docgen on ansible directory (playbook dir or role dir).

Context

Dockerfile:

FROM python:3.9-slim
RUN pip install ansible-docgen
WORKDIR /app

Run docker image:

docker run -ti --rm -v $PWD:/app ansible-docgen:latest ansible-docgen -p ansible-playbooks/roles/myrole

Error stacktrace:

Traceback (most recent call last):
  File "/usr/local/bin/ansible-docgen", line 7, in <module>
    cli.run()
  File "/usr/local/lib/python3.9/site-packages/ansibledocgen/cli.py", line 37, in run
    self.dirparser = DirParser(project)
  File "/usr/local/lib/python3.9/site-packages/ansibledocgen/parser/dir.py", line 20, in __init__
    self.playbookparser.parse_playbooks()
  File "/usr/local/lib/python3.9/site-packages/ansibledocgen/parser/playbook.py", line 20, in parse_playbooks
    self.parse_playbook(playbook)
  File "/usr/local/lib/python3.9/site-packages/ansibledocgen/parser/playbook.py", line 52, in parse_playbook
    yamldata = yaml.load(data)
TypeError: load() missing 1 required positional argument: 'Loader'

How to reproduce?

docker build . -t ansible-docgen:latest
docker run -ti --rm -v $PWD:/app ansible-docgen:latest ansible-docgen -p ansible-playbooks/roles/myrole

Currently, ansible-docgen always creates a README.md as the default markdown doc. User should be given a choice to specify a filename of his choice. Something like the below :

ansible-docgen -f playbook_info

  ...generates playbook_info.md

In my case, the README is a file containing info about the general purpose of a set of playbooks OR roles in a folder. While I would love to have the doc telling me about the specifics/summary of each playbook/role , I wouldn't want it to replace the README.md

Of course, it could be argued that the original README can be moved to a different filename - but somehow I would like to have original README as the readme a user should be directed to.

It should not write any documentation for something it knows nothing about. For example some var files have .yml, these currently would be documented with no information (taking up space and an eye sore).

Incorrectly formatted .yml files cause this error:
The original error was:
$ansible-docgen
Traceback (most recent call last):
File "/usr/local/bin/ansible-docgen", line 7, in
cli.run()
File "/Library/Python/2.7/site-packages/ansibledocgen/cli.py", line 37, in run
self.dirparser = DirParser(project)
File "/Library/Python/2.7/site-packages/ansibledocgen/parser/dir.py",
line 15, in init
self.roleparser = RoleParser(self.ansiblecfg.get_role_paths())
File "/Library/Python/2.7/site-packages/ansibledocgen/parser/role.py",
line 18, in init
self.parse_main_tasks()
File "/Library/Python/2.7/site-packages/ansibledocgen/parser/role.py",
line 39, in parse_main_tasks
self.playbookparser.parse_playbooks()
File "/Library/Python/2.7/site-packages/ansibledocgen/parser/playbook.py",
line 20, in parse_playbooks
self.parse_playbook(playbook)
File "/Library/Python/2.7/site-packages/ansibledocgen/parser/playbook.py",
line 52, in parse_playbook
for task in yaml.load(data):
TypeError: 'NoneType' object is not iterable

It would be nice to include required variables and optional variables in the output.

Instead of string replaces, look at using jinja2.

It should not display the author if not defined.

Thinking:

[ "playbook1" : { "author": "test",
"description": "test2",
"task_names": ["str1", "str2"],
"rolename" : None,
"relative_path" : "./myplaybook.yml"} ]

It only knows about the otherroles path, and not the roles path. It then parses the roles path expecting playbooks.

1. Need to improve ability to detect role paths and exclude them without them being defined.
2. Need to see how Ansible handles this itself. What does Ansible do if you define an alternate role path, yet still have a standard "roles" directory.

Clean up code base with better documentation and pep compliance and passing lint tests.

Look at how playbook parses rolename, see if maybe that should be
passed to as a parameter rather than parsing it twice.

Example:
./bin/ansible-docgen -p test/integration/project1

This does bad things

Search for occurances of "%s%s" and use filename =
os.path.join(playbookpath, "README.md") instead. Mostly found in
markup.py.

Traceback (most recent call last):
File "/bin/ansible-docgen", line 7, in
cli.run()
File "/usr/lib/python2.7/site-packages/ansibledocgen/cli.py", line 44, in run
self.formatter.write_files()
File "/usr/lib/python2.7/site-packages/ansibledocgen/formatter/markup.py", line 115, in write_files
p.write("%s" % line)
UnicodeEncodeError: 'ascii' codec can't encode character u'\xf3' in position 34: ordinal not in range(128)