Contributing to the Documentation

Did you just have to trawl through source code to find out what something does?
Did you have to ask someone on IRC?
Have you just proudly accomplished your task despite the documentation's lack of relevant information?

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.

The documentation for roles lives in doc/ansible/roles/.

You can build the documentation yourself on your local fork by running make docs from your project folder.

Migration artifacts

Due to how the DebOps project was structured during earlier days of developent, the practice was to .. include:: an ../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 include, feel free to remove it and fix the page so it builds without it.

Documentation suggestions

These are a few subjects the current documentation is lacking.

User Manual

  • Debugging tips: How to find and fix bugs in DebOps

Admin Recipes

  • 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

Developer Guide

  • 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