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. The approach that we will learn will be transferable to GitLab Pages and Bitbucket Pages.
|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?|