Code documentation lesson

The documentation on this webpage is made to help users of the clusters offered by Sigma2 to run and contribute to the development of the Community Terrestrial Systems Model (CTSM).

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

Here we will learn the stuff you normally see. This is more and more.

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

The lesson

• Motivation and wishlist
• Popular tools and solutions
• In-code documentation
• Writing good README files
• Sphinx and reStructuredText
• Deploying Sphinx documentation to Read the Docs
• Hosting websites/homepages on GitHub Pages
• Summary

Reference

• Credit