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 eveything 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
Fixing broken links
While working with the documentation, the :ref:`make links<cmd_make_links>` command can be used to spot and fix broken external links.
- Broken links should be corrected or omitted
- Permanent redirects should be pointed to the new addresses
- Temporary redirects are fine and the listed links are usually desirable
Due to how the DebOps project was structured during earlier days of developent,
the practice was to
.. include:: an :file:`../includes/global.rst` to
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