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 use the docs workflow in skare3. This workflow does roughly the following:

PACKAGE=parse_cm
RELEASE=3.8.0
git clone git@github.com:sot/${PACKAGE}.git -b ${RELEASE} source
git clone git@github.com:sot/${PACKAGE}.git -b gh-pages gh-pages
cd source/docs
make html
open _build/html/index.html  # Check build
rsync -av --delete _build/html/ ../../gh-pages/docs/
cd ../../gh-pages
git add *
git commit -m 'update docs'
git push

To use this workflow each repository needs a workflow like this:

---
name: Deploy Docs
on:
  release:
    types:
    - released
  repository_dispatch:
    types:
    - build-docs

jobs:
  docs:
    uses: sot/skare3/.github/workflows/package_docs.yml@master
    secrets:
      CHANDRA_XRAY_TOKEN: ${{ secrets.CHANDRA_XRAY_TOKEN }}