outbit / ansible-docgen Goto Github PK
View Code? Open in Web Editor NEWGenerate documentation from annotated Ansible Playbooks and Roles
Home Page: https://pypi.org/project/ansible-docgen/
License: MIT License
Generate documentation from annotated Ansible Playbooks and Roles
Home Page: https://pypi.org/project/ansible-docgen/
License: MIT License
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).
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 :
# 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"
## Playbook: [sampletest.yml](sampletest.yml)
> **Author:** ksatchit
> **Description:** ansible-docgen issues with block
> **Task:** First task in the playbook
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 would be nice to include required variables and optional variables in the output.
The error TypeError: load() missing 1 required positional argument: 'Loader'
comes up at running the docgen on ansible directory (playbook dir or role dir).
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'
docker build . -t ansible-docgen:latest
docker run -ti --rm -v $PWD:/app ansible-docgen:latest ansible-docgen -p ansible-playbooks/roles/myrole
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.
Search for occurances of "%s%s" and use filename =
os.path.join(playbookpath, "README.md") instead. Mostly found in
markup.py.
Make it so inside of comments you can use jinja2 to do more advanced formatting.
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
attribute would be nice. Make the attributes bold.
Instead of string replaces, look at using jinja2.
Clean up code base with better documentation and pep compliance and passing lint tests.
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)
Look at how playbook parses rolename, see if maybe that should be
passed to as a parameter rather than parsing it twice.
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.
Traceback (most recent call last):
File "/home/tsiakalt/.local/bin/ansible-docgen", line 7, in <module>
cli.run()
File "/home/tsiakalt/.local/lib/python3.7/site-packages/ansibledocgen/cli.py", line 37, in run
self.dirparser = DirParser(project)
File "/home/tsiakalt/.local/lib/python3.7/site-packages/ansibledocgen/parser/dir.py", line 20, in __init__
self.playbookparser.parse_playbooks()
File "/home/tsiakalt/.local/lib/python3.7/site-packages/ansibledocgen/parser/playbook.py", line 20, in parse_playbooks
self.parse_playbook(playbook)
File "/home/tsiakalt/.local/lib/python3.7/site-packages/ansibledocgen/parser/playbook.py", line 52, in parse_playbook
yamldata = yaml.load(data)
File "/usr/local/lib/python3.7/dist-packages/yaml/__init__.py", line 114, in load
return loader.get_single_data()
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 51, in get_single_data
return self.construct_document(node)
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 60, in construct_document
for dummy in generator:
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 413, in construct_yaml_map
value = self.construct_mapping(node)
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 218, in construct_mapping
return super().construct_mapping(node, deep=deep)
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 143, in construct_mapping
value = self.construct_object(value_node, deep=deep)
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 100, in construct_object
data = constructor(self, node)
File "/usr/local/lib/python3.7/dist-packages/yaml/constructor.py", line 429, in construct_undefined
node.start_mark)
yaml.constructor.ConstructorError: could not determine a constructor for the tag '!vault'
in "<unicode string>", line 32, column 19:
password: !vault |
Example:
./bin/ansible-docgen -p test/integration/project1
This does bad things
Example cli:
-i description,task
It should not display the author if not defined.
Expected playbook format:
Currently it does not parse a playbook because it expects a list, It
should infact expect a dictionary with ["tasks"] being a list.
Needs some design work so it looks a little better and not so plain.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.