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

  1. Basic understanding of Git.

  2. You need to have Sphinx installed (as part of your Python environment installation).

  3. For the GitHub Pages part you need a GitHub account.

15 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 reStructuredText

20 min

Deploying Sphinx documentation to Read the Docs

20 min

Hosting websites/homepages on GitHub Pages

5 min

Summary