Contributing to the Documentation¶
Well, help us improve it!
DebOps' documentation is written in reStructuredText,
built with Sphinx, hosted on readthedocs
and lives in the
docs/ folder of the monorepo.
You can build the documentation yourself on your local fork by running make docs from your project folder.
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 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
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