Documentation Guide

Sphinx Documentation

Style

The documentation currently uses a variety of docstring styles, but we would like to converge to using only numpy-style docstrings. In the process of converting docstrings to numpy-style, pyments might be of use.

Ska Theme

We use a custom sphinx theme that is based on astropy's theme. We configure the theme like by including something like the following in conf.py:

html_theme = 'bootstrap-ska'
html_theme_options = {
    'logotext1': 'Ska! ',  # white,  semi-bold
    'logotext2': 'ska_helpers',  # orange, light
    'logotext3': '',   # white,  light
    'homepage_url': 'https://sot.github.io/',
    'homepage_text': 'ska',
    'homepage_text_2': 'tools'
}

Github Pages

All package's documentation is automatically deployed to gh-pages. The main page pointing to all packages is https://sot.github.io. Any changes to that page are done on the sot/sot.github.io repository.

Enabling

To enable this at the package level, we create an 'orphan' branch called gh-pages. Something like this (WARNING: this removes untracked files you might have in the directory):

git checkout --orphan gh-pages
git rm -rf .
git clean -fd
git commit --allow-empty -m 'root gh-pages commit'
mkdir docs
touch docs/.nojekyll
git add docs/.nojekyll
git ci docs/.nojekyll -m 'added nojekyll'

Note the nojekyll files to prevent the automated documentation from github from trying to build.

After pushing the gh-pages branch, go to the repository 'settings' page,to the 'GitHub Pages' section. There, the source of the documentation should be set to 'Branch: gh-pages', and the folder should be 'docs'

Deploying

To deploy the docs, we normally checkout the repository twice, side by side, something like:

git clone git@github.com:sot/aca_helpers.git -b master source
git clone git@github.com:sot/aca_helpers.git -b gh-pages gh-pages
cd source/docs
make html
mv _build/html/* ../../gh-pages/docs
cd ../../gh-pages
git add *
git commit -m 'update docs'
git push