Divio documentation for developers

Published version: Divio developer handbook.

This documentation is intended for developers using Divio.

Build the documentation locally

You'll need the enchant library, used by pyenchant for spelling.

Install with brew install enchant (macOS) or the appropriate command for your system.

Then:

git clone git@github.com:divio/divio-cloud-docs.git  # clone
cd divio-cloud-docs
make install  # create a virtualenv and install required components
make run  # build and serve the documentation
open http://localhost:9001  # open it in a browser

Notable techniques used in this documentation

Read the Docs

We serve our documentation via Read the Docs, a superb free service that's especially well-known in the Python world, and is ideal for open-source projects.

The documentation is written in ReStructed Text (RST) and built using Sphinx.

Read the Docs also offers a commercial service via readthedocs.com.

Ad-hoc CSS/JS in pages

We do this on a few pages, where we need something extra.

It's as simple as:

.. raw:: html

    <style>
        p {color: red;}
    </style>

at the top of the page to add some styles. See the raw version of the main index.html page for an example.

We use this to...

Create responsive columns

See docs.divio.com. There, we add the styles you see in the example above, and apply appropriate classes to the elements:

 ..  rst-class:: clearfix row

 ..  rst-class:: column column2


 :ref:`Tutorial <introduction>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Get started with a hands-on introduction to Divio for developers.

 ..  rst-class:: column column2


 :ref:`How-to guides <how-to>`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 Step-by-step guides for the developer covering key operations and procedures


 [...]

 ..  rst-class:: clearfix row

 About Divio
 ------------

Create an interactive debugging checklist

When a deployment fails on our Cloud, our Control Panel will direct you to the interactive debugging checklist.

It's a kind of Choose your own adventure story, but probably less fun.

This checklist relies on styles and JavaScript.

Sphinx and intersphinx extensions

If you don't already use intersphinx, you should.

This allows us to link directly to (for example) references in other Sphinx projects, such as where we link to django CMS's caching settings.

The trick here is that unlike :ref: for example, setting: is not a natively understood by Sphinx - meaning that there isn't by default a way to refer to those in another project. However, we can extend Sphinx's capacities.

See our extensions.py for how we do this (we simply steal the extensions.py from django CMS).

A reference then looks like:

:setting:`django-cms:CMS_CACHE_DURATIONS`

Documentation structure and standards

Our documentation structure is key to its usability. See our What nobody tells you about documentation for an explanation of why it's important and how it works.

kinkerl/divio-cloud-docs