How to document your research software

In this lesson we will discuss different solutions for implementing and deploying code documentation.

We will start with a discussion about what makes a good README. For many projects, a README is more than enough.

We will then learn how to build documentation with the documentation generator Sphinx (and compare it with others) and how to deploy it to Read the Docs, a service which hosts open documentation for free.

This demonstration will be independent of programming languages.

We will also learn how to deploy a project website or personal homepage to GitHub Pages. The approach that we will learn will be transferable to GitLab Pages and Bitbucket Pages.

Prerequisites

Basic understanding of Git.
For the Sphinx part, You need to have sphinx and sphinx_rtd_theme installed (they are part of the coderefinery environment).
For the GitHub Pages part you need a GitHub account.

10 min	Motivation and wishlist
10 min	Popular tools and solutions
20 min	In-code documentation
30 min	Writing good README files
30 min	Sphinx and Markdown
20 min	Deploying Sphinx documentation to GitHub Pages
20 min	Hosting websites/homepages on GitHub Pages
5 min	Summary

The lesson

Reference

About