Template for automating documentation

README.md

Documentation template

This gist is a template for starting with sphinx documenation

It has a docker container for easy deployment. It integrates with dash.app using doc2dash and creates a feed so you can keep local docs up to date

Things you need to do:

• install requirements pip install -r requirements.txt
• run sphinx-quickstart to get you set up
• edit the dockerfile (DOCS_NAME, DOCS_SOURCE, DOCS_REMOTE need changing)

I assume your compiled docs have an index.html at the root

Give things a test! build & run the container. it exposes port 80

there should be a dash feed at /dash_feed.xml and it should link to a tarball of your dash docs

you can install your docs in dash by opening a uri like:

dash-feed://http%3A%2F%2Fyoursite.com%2Fdash_feed.xml (you can link to it from within your docs to make it easier) dash should detect updates when you re-deploy your docs

References:

• sphinx: http://sphinx-doc.org/index.html
• dash app: https://kapeli.com/dash
• doc2dash: https://doc2dash.readthedocs.org/en/2.0.2/index.html
• about docset feeds: https://kapeli.com/docsets#dashdocsetfeed

build.sh

#!/bin/bash

#This script is for building inside the docker container
#use the makefile from sphinx-quickstart if you want to build things locally

set -e

cd ${DOCS_ROOT:?"DOCS_ROOT must be set"}

mkdir -p build/html
mkdir -p build/dash

sphinx-build -b html $DOCS_ROOT/source $DOCS_ROOT/build/html

doc2dash -n ${DOCS_NAME:?"DOCS_NAME must be set"} -d build/dash build/html

tar -cvzf $DOCS_NAME.tgz build/dash/$DOCS_NAME.docset
version=$(cat "$DOCS_NAME.tgz" | md5sum | cut -f 1 -d " ")

mkdir -p build/html/dash
mv $DOCS_NAME.tgz build/html/dash

cat <<EOF > build/html/dash_feed.xml
<entry>
    <version>$version</version>
    <url>http://${DOCS_REMOTE:?"DOCS_REMOTE must be set"}/dash/$DOCS_NAME.tgz</url>
</entry>
EOF

Dockerfile

FROM ubuntu:14.04
# ---- Edit These ----
ENV DOCS_NAME=template
ENV DOCS_SOURCE=source
ENV DOCS_REMOTE=http://yoursite.com
# --------------------
# docs remote is used in the dash feed url, see build.sh

ENV DOCS_ROOT=/var/www
ENV DEBIAN_FRONTEND=noninteractive
# Install supervisor & nginx & python
RUN apt-get update && apt-get install -y supervisor nginx python python-dev software-properties-common python-pip
# Install some libraries required by dependencies of sphinx
RUN apt-get install -y libxml2-dev libxslt1-dev zlib1g-dev lib32z1-dev

#remove default nginx files (except mime.types)
RUN mv /etc/nginx/mime.types /etc/tmp
RUN rm -rf /etc/nginx/*
RUN mv /etc/tmp /etc/nginx/mime.types

#set up some directories
RUN mkdir -p /var/log/supervisor

COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY nginx.conf /etc/nginx/
COPY $DOCS_SOURCE $DOCS_ROOT/source
COPY build.sh $DOCS_ROOT/
COPY requirements.txt $DOCS_ROOT/

RUN pip install -r $DOCS_ROOT/requirements.txt
RUN $DOCS_ROOT/build.sh

EXPOSE 80
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

nginx.conf

user www-data;
worker_processes 4;
pid /var/run/nginx.pid;
daemon off;

events {
    #defaults are fine
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;

    access_log /var/log/nginx/error.log;
    error_log /var/log/nginx/error.log;

    gzip on;
    gzip_disable "msie6";

    server {
        listen 80 default_server;

        root /var/www/build/html;
        index index.html;

        # Make site accessible from http://localhost/
        server_name localhost;

        location / {
            try_files $uri $uri/ =404;
        }
    }
}

requirements.txt

Sphinx==1.3.1
doc2dash==2.0.2

supervisord.conf

[supervisord]
nodaemon=true

[program:nginx]
command=/usr/sbin/nginx
directory=/etc/nginx