Fork me on GitHub
Credit and license

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 Python 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.

Prerequisites

  1. Basic understanding of Git.

  2. You need a GitHub account.

  3. You need a Read the Docs account.

  4. 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:50 Popular tools and solutions What tools are out there?
What are their pros and cons?
16:00 Sphinx and ReStructuredText How do we get started on writing Sphinx documentation in RST?
16:20 Deploying Sphinx documentation to Read the Docs How do Python projects deploy their documentation?
Can we use their solutions for projects which do not use Python?
16:40 Deploying a project website to GitHub Pages How can we have a good-looking project website without hosting it ourselves?
16:55 Recommendations What recommendations can we take home?
17:00 Finish