Quick and Pretty Docs for Software Projects

I have practiced Readme Driven Development on a number of my projects with varying milage. I have often found myself wishing for a few things:

  1. More structure When writing the documentation, and even more so when reading it. A single markdown file starts getting out of hand really quickly. On my presonal projects I go for org-mode, which keep me satisfied. But when working on a professional gig, it don't feel right to force other developers into org-mode/emacs.
  2. Prettiness Markdown is a quite reasonably readable format, but there is always room for prettyness.

Basically I wish for github-pages with more structure; so, a statically generate site.

To minimize the added complexity to our dev setup, and since I am already using docker to run dev-environments for almost all of my projects, I chose to leverage it for building my readme as a local "service". i.e I chose to structure my documentation with filesystem, and use docker to abstract the complexity of setting up the static site generator.

I have chosen hugo because of its simplicity. Its intuitive content management means near-zero learning curve for my teammates to start contributing documentation. I chose hugo-theme-learn because of its simplicity, mermaid.js support for UML diagrams, and well, prettiness.

I have a directory named docs in our repository, with following general structure:

├── config.toml
├── content
└── Dockerfile

Every markdown file in content directory adds to the generated documentation.

Here is the Dockerfile I have used to create the docs container. It downloads and sets up hugo with the theme in a single command without anything other than docker installed on a developer's machine.

FROM alpine:latest



RUN apk update && apk add hugo git

ENV HUGO_THEME_URL='https://github.com/matcornic/hugo-theme-learn'

RUN mkdir -p /themes/current \
  && cd /themes/current \
  && git init \
  && git remote add origin $HUGO_THEME_URL \
  && git fetch --depth 1 origin $HUGO_THEME_COMMIT \
  && git checkout FETCH_HEAD \
  && cd /app
RUN echo "alias hugo='hugo --themesDir /themes --theme current'" > ~/.profile

COPY . /app

CMD hugo serve --port 3000 --bind='' --themesDir /themes --theme current

When exposed on port 3000, it allows live-reloading of docs and search in docs as well. It is possible to change the theme and theme version by setting environment variables HUGO_THEME_URL and HUGO_THEME_COMMIT when building the docker image.

Here is config.toml file I've used for my docs, which allow me to configure the hugo theme with above mentioned environment variable only:

buildDrafts = true
title = "My Project"

# For search functionality
home = [ "HTML", "RSS", "JSON"]

  author = "My team"
  description = "My project's cloud"