How to document your research software
In this lesson we will discuss different solutions for implementing and deploying code documentation.
This demonstration will be mostly independent of programming languages (you will be able to follow and do all the exercises using the CodeRefinery conda environment).
We will start by discussing the form of documentation which is the most immediate to write: in-code comments, and docstrings.
To step up our game we will discuss what makes a good README. For many projects, a curated README is enough.
We will then learn how to build documentation with the documentation generator Sphinx and how to deploy it to GitHub Pages. The approach that we will learn will be transferable to GitLab Pages and Bitbucket Pages.
After we have seen Sphinx as an example, we will see a brief taxonomy of the other popular tools and solutions, and finally, once we know what tooling can do and how to use it, we will take a step back and look at best practices: what makes documentation important and useful and how to best maintain it.
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.
If you wish to follow in the terminal and are new to the command line, we recorded a short shell crash course.
An optional episode is about deploying a project website or personal homepage to GitHub Pages.
5 min |
Intro |
5 min |
|
10 min |
|
35 min |
Sphinx and Markdown (with exercise) |
10 min |
Break |
30 min |
Deploying Sphinx documentation to GitHub Pages (with exercise) |
10 min |
|
10 min |
|
5 min |
The lesson
Supplementary material
About