Security News
Introducing the Socket Python SDK
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Generate documentation from annotated playbooks and roles using templates.
Note: this project is currently in Beta, issues, ideas and pull requests are welcome.
# install
pip install ansible-autodoc
# print help
ansible-autodoc -h
# print parsed annotation results in the cli
ansible-autodoc -p all path/to/role_or_playbook
# generate README file based on annotations
ansible-autodoc [path/to/project]
notes:
Use the following annotations in your playbooks and roles
# @meta author: Author Name
# @meta description: Project description
# @todo bug: bug description
# @todo improvement: improvement
# @action install # this action describes the installation
# @action # this action does not have a section, only description
# @tag tagname # tag description
# @var my_var: default_value # description of the variable
# @var my_var: default_value # description of the variable
my_var: default_value
# @example # the hash is needed due to the parser constrains
# my_var:
# - subitem: string
# - subitem2: string
# @end
ansible-autodoc comes with 3 templates out of the box, the default is "readme", you can change this in configuration.
If you want to create your own project specific templates, see the template documentation
If a file already exists in the output, the you will be prompted to overwrite or abort.
The default "readme" template will generate a README.md file in the root of the project, detailing the sections:
you can extend this my creating a file "_readme_doby.md"
in the root of your project, this will be included in the rendered Readme just after the
initial description.
The "doc_and_readme" template is an extended template intended to be used playbook projects with several roles, it will generate a minimal README.md file and a documentation subfolder "doc" with more detailed information.
you can extend this my creating a file "_readme_doby.md"
in the root of your project, this will be included in the rendered Readme just after the
initial description.
the files created in the documentation folder will cover:
you can extend the documentation in this folder, just keep in mind that generated files will be overwritten.
The "cliprint" template is used to display the content when you use the command line print parameter "-p"
you can create a configuration file "autodoc.config.yaml" in the root of your project in order to modify several behaviours, see the sample config file for more details:
# role or project with playbooks
$ cd <project>
# create sample configuration (optional)
# you can pass the options as parameters too
$ ansible-autodoc --sample-doc > autodoc.config.yaml
FAQs
Generate documentation from annotated playbooks and roles using templates
We found that ansible-autodoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.
Security News
A new Rust RFC proposes "Trusted Publishing" for Crates.io, introducing short-lived access tokens via OIDC to improve security and reduce risks associated with long-lived API tokens.