Docs Developer Guide

This document is for contributors working on the design, templating, deployment, or development of the ODK Docs website.

Tech Overview

ODK Docs uses:

Custom HTML templating

ODK Docs uses the sphinx_rtd_theme, with some minor customizations.

ODK-specific versions of HTML/Jinja templates are in _templates. Any file in that directory will override the file of the same name in the sphinx_rtd_theme source.

So, to customize a portion of the HTML template, copy the source file from sphinx_rtd_theme and then edit it.

Please commit the copied file unchanged before editing, so that it is easy to track what you have changed.

Custom JavaScript

Custom JavaScript should be added in src/_static/js/custom.js. Comment your code with an explanation of what the JS accomplishes, and a reference to the issue number you are working on.

The ODK Docs template includes JQuery, so you can use it in your custom JS.

Custom CSS

Custom CSS should be added in src/_static/css/custom.css. Comment your code with an explanation of what the CSS accomplishes and a reference to the issue number you are working on.

For example:

/* Example CSS PR #xyx */

div[class^='example'] {
  color: black;
}

It is helpful to keep the CSS file organized. There are several sections in the custom.css file:

  • Styling for rst roles and directives
  • Responsive CSS
  • Styling for JS implementation
  • Utility classes

Each of these sections are enclosed in start and end comments. Add your code to the relevant section. If you don't find any section relevant, add a new section and add your code there.

For example:

/* New section starts */

/* Example CSS PR #xyx */

div[class^='example'] {
  color: black;
}

/* New section ends */