Contributing to the Documentation
Well, help us improve it!
The documentation for roles lives in
The main entry points for role documentation are:
index.rstgenerates the top-level pages for the html documentation
man_index.rstgenerate the role manpages
To keep things uniform, sections go in the following order:
getting_started.rstcovers initial configuration and basic usage
Guides, examples and anything else specific to the role's responsibilities
dependent.rstdescribes usage as a dependent role
Default Variables gets populated from inline markup in roles'
defaults-detailed.rstcontains details for complex variables
defaults-*.rst, for roles with different types of complex variables
ldap-dit.rstdescribes the LDAP Directory Information Tree a role utilizes
The manpages follow the same order, however
ldap-dit are omitted. They also have their own special files:
Before everything else:
man_synopsis.rstprovides a short hint for command line usage
man_description.rstprovides a description of the role. This also gets included at the top of
index.rstwhen rendering the html.
After everything else:
man_seealso.rstmentions any other relevant manpages or links.
Of course, due to DebOps' wide variety of roles, their documentation can also
vary greatly. Plenty of roles are just fine with just a
defaults/main, and the introductory
Due to how the DebOps project was structured during earlier days of developent,
the practice was to
.. include:: an
share references between multiple git repositories.
The current best practice is to use dynamically generated references,
so if you are editing a file in the documentation and you spot this
feel free to remove it and fix the page so it builds without it.
These are a few subjects the current documentation is lacking.
Debugging tips: How to find and fix bugs in DebOps
Host Preparation: Describe how DebOps hosts should be prepared (bootstrapped) for management
Common Configuration: Describe default configuration applied on hosts by the common playbook
Basic virtualization: Describe virtualization on a basic level with LXC, libvirt+KVM
Basic mail server: Describe mail server setup with Postfix, Dovecot
Development network: Describe Vagrant replacement, a development network with DNS, DHCP, PXE and preseeding
Monorepo layout: How the DebOps github monorepo is structured
Code standards: How to write Ansible roles for DebOps
Software sources: How DebOps handles external software
Project roadmap: Long term plans for DebOps
GitLab CI tests: How DebOps is tested on GitLab CI
Vagrant documentation: Information about Vagrant usage in tests
Jane documentation: Information about Jane
Testinfra documentation: Information about testinfra usage