Fork me on GitHub

Code documentation lesson

In this lesson we will discuss different solutions for implementing and deploying code documentation. We will learn how to build documentation with the documentation generator Sphinx 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 and relevant also for your Fortran, C, C++, R, or Matlab projects. We will also learn how to deploy a project website to GitHub Pages. The approach that we will learn will be transferable to GitLab Pages and Bitbucket Pages.

Prerequisites

  • Basic understanding of Git.
  • You need a GitHub account.

Optional requirements (to set up own Sphinx/ Read the Docs project)

  • You need a Read the Docs account.
  • You need to have Sphinx installed (as part of your Python environment installation).

Schedule

15:30 Motivation Why is code documentation important?
15:35 Specs and requirements What requirements and specifications can we impose on a good documentation?
15:45 Recommendations What tools can we recommend?
15:55 Sphinx and Read the Docs exercise
16:30 Adding Sphinx to your own project
16:55 How to hook up your own project with Read the Docs
17:20 Deploying a project website or homepage to GitHub Pages How can we have a good-looking project website without hosting it ourselves?
17:40 Finish