Documentation notes

Overview

Teaching: 30 min
Exercises: 30 min

Questions

• References on documenting code

Objectives

• Learn how do document procedures, python and C++

General text formatting in Markdown

Markdown Cheatsheet

Github markdown

Advanced github formatting

https://github.com/hsf-training/carpentry-cookiecutter

Generating lessons like this

HSF

Documenting complex python packages with sphinx and readthedocs

sphinx is a documentation system for python code that can be used with rst or with Markdown. You can set up github actions to build custom <organization>.github.io pages from repository github.com/<organization>.

Alternatively readthedocs is a semi-commercial system that uses sphinx/rst and provides the build infrastructure.

C++

doxygen

Key Points

• This will be useful for a lot of projects

• It is also something almost all people who get paid to program are expected to know well