All in One View

Content from Introduction

Last updated on 2026-06-16 | Edit this page

Estimated time: 30 minutes

Overview

Questions

  • Why is documenting software important?
  • How should we document our code?
  • What are the minimum elements of software documentation needed?

Objectives

  • Describe the main types of software documentation and identify their primary audiences, including end users, developers, maintainers, contributors and system administrators.

This session introduces the importance of documenting our software. We also discuss different types of software documentation aimed at various target audiences, including end users, developers, maintainers, administrators and contributors.

What is software documentation?

Software documentation provides the information needed to understand, use, maintain and reuse software. It explains the software’s purpose, functionality, installation, configuration and operation - helping users and contributors work with the software effectively.

Documentation also captures important software project information and metadata that support long-term sustainability and reuse. This may include details about licensing, project ownership and maintenance, contributor roles, contact information, support channels, issue reporting processes and guidance on how the software should be cited and credited. Together, this information helps ensure that software remains accessible, reusable and maintainable throughout its lifecycle.

Who is documentation for?

Different audiences interact with our software in different ways and therefore require different types of documentation. Understanding who your documentation is for helps you decide what information to include, how much detail to provide, and the style in which it should be written.

Common audiences for software documentation include:

  • End users want to use the software to achieve a goal rather than understand how it is implemented. They need documentation that helps them install, learn, and operate the software efficiently.
  • Developers work on the software’s codebase to add features, fix bugs and improve functionality. They need technical information that helps them understand how the software works (covering software architecture, code structure, APIs, testing procedures) and information on development workflows/practices so they can contribute code effectively.
  • Contributors contribute to the project but may not be part of the core development team. They need guidance on contribution processes, project expectations, coding standards and community practices. Code contributors will also need access to developer documentation.
  • Maintainers are responsible for the long-term health and sustainability of the software project. They need documentation covering releases, governance, maintenance procedures, project management, and decision-making processes, as well as technical developer documentation.
  • System administrators deploy, configure, monitor and maintain software in operational environments. They need documentation on installation, configuration, deployment, system requirements, security, monitoring, backup and troubleshooting (but may not need to know all the implementation/code details or design decisions).

You may not have all of these audiences for your software, but you will almost certainly have end users and developers. A single document may serve multiple audiences, so information does not necessarily need to be duplicated. For example, installation documentation can be useful to end users, developers, contributors, maintainers and system administrators alike.

When planning documentation, identify your primary audiences and ensure that each has access to the information they need to successfully use, contribute to, maintain or operate the software.

Why does documenting software matter?

Reproducibility is the cornerstone of science, and scientists who work in many disciplines are expected to document the processes by which they have conducted their research so it can be reproduced by others. In medicinal, pharmacological, and similar research fields for example, researchers use logbooks which are then used to write up protocols and methods for publication. For research that relies on software - the software itself is one way of documenting the research method.

Software documentation is often seen as a time-consuming task with few immediate rewards and is therefore frequently neglected in research projects. However, documentation is an essential part of software development and research practice. Good documentation not only helps others understand and use software (i.e. supports reusability), but also improves the quality and sustainability of the software and reproducibility of the research it supports.

Good software documentation:

  • captures important methodological details that can be referenced when publishing research findings or preparing reports and papers.
  • helps you revisit a project more easily after weeks, months, or even years away from it.
  • makes software easier to understand, reuse, modify and build upon (to do something else), increasing its visibility, adoption and potential impact.
  • supports reproducible research by providing clear information about how the software works and how it should be used.
  • facilitates collaboration by helping new team members quickly understand the project and become productive.
  • reduces support requests and saves time by answering common questions and providing guidance for users.
  • improves software sustainability by making it easier to maintain, update, and transfer knowledge between project members.

In short, documentation is an investment that benefits both current and future users of a software project.

Types of software documentation

Software documentation can be produced at different levels and for different audiences. A useful way to think about documentation is to group it into three broad categories:

  • Code-level documentation – information embedded within the source code that explains how the code works.
  • Software-level documentation – documentation that explains how to install, use, configure and edit the code.
  • Project-level documentation – documentation that describes the wider software project, including its governance, maintenance, licensing, contribution guidelines, support and sustainability.

These categories complement one another and together provide the information needed to develop, use, maintain, and reuse software effectively. In the following sections, we will explore each type in more detail.

Code-level documentation

Common forms of code-level documentation include comments and documentation strings (docstrings).

Code comments are free-text explanations of how specific lines of code work (e.g. logic and implementation details) and are ignored by the interpreter or compiler.

Docstrings are built-in literal strings placed immediately after the definition of a function, class, module, or method that follow a certain syntax. They explain how to use the code — including its arguments, return values, and usage — so that other developers and automated tools can understand it without reading the implementation. Unlike comments, docstrings are retained as part of the running program, and many tools can automatically display docstring information as part of an interactive documentation or help system (as we will see later on in this lesson).

Comments help convey the context, rationale, and implementation logic of the code. They can serve as useful reminders about why code was written in a particular way, how it achieves a specific task or the real-world implications of its behaviour.

Target audience for this type of documentation: developers and maintainers of the software, including your future self.

When writing comments, keep the following principles in mind:

  • Focus on why the code exists and how it works, rather than simply describing what it does.
  • Avoid comments that merely repeat information that is already obvious from the code.
  • Prefer clear, readable code over excessive commenting. If a section of code is difficult to understand, consider refactoring it before adding explanatory comments.
  • Keep comments concise and focused. Large blocks of text are difficult to read and maintain.
  • Update comments whenever the code changes. Outdated or misleading comments can be more harmful than having no comments at all.
  • Use comments to record important assumptions, limitations or workarounds that may not be apparent from the code itself.

Software-level documentation

Comments and docstrings improve the readability and maintainability of source code, but they are not sufficient on their own to make software easy to use, understand, deploy or contribute to. This requires additional software-level documentation aimed at different audiences and their specific needs.

Common examples of software-level documentation include:

  • Technical documentation for developers, maintainers, contributors and system administrators including high-level software architecture descriptions, API documentation, setup and deployment guides, configuration instructions, testing procedures, error codes and troubleshooting information.
  • User documentation for end users including installation guides, tutorials, user manuals, example workflows, FAQs and troubleshooting guides that help users learn and use the software effectively without requiring direct support from the development team.

A useful framework for organising software documentation is Diátaxis (shown in the diagram below), which categorises documentation according to the needs of the reader and the purpose the documentation serves.

Diátaxis identifies four complementary types of documentation:

  • Tutorials - lessons that guide learners through a series of exercises to build proficiency using the code. Target audience: new users and learners who are unfamiliar with the software.

  • How-to guides - step by step instructions on how to accomplish specific goals using the software. Target audience: existing users who want to complete a particular task.

  • Reference documentation - lookup material that helps users find precise information about the software, such as functions, commands, parameters, APIs, and configuration options. Reference documentation can often be generated automatically from code-level docstrings. Target audience: developers, advanced users, and maintainers who need accurate technical details.

  • Explanations - conceptual discussions that help users understand implementation decisions, design choices, and underlying principles.

  • Target audience: developers, maintainers, contributors and system administrators who need to understand the reasoning behind the software.

Other documentation frameworks and communities, such as Write the Docs and The Good Docs Project, provide a wealth of resources to help teams create high-quality documentation.

You do not need to provide every documentation type described above. Instead, focus on creating documentation that meets the needs of your intended audiences. The exact mix of documentation will depend on your software, its complexity, and the people who use, contribute to, deploy and maintain it.

Project-level documentation

Project-level documentation includes information and metadata that help others discover, understand, evaluate, cite, reuse, and contribute to software.

Target audience: end users, developers, contributors, project managers, funders, and anyone evaluating or reusing the software.

A common way to provide project-level documentation is to include metadata files within the software repository alongside the code. Some common examples are shown below.

File Description
README Provides an overview of the project, including links to installation, usage, dependencies, other metadata files and technical documentation.
CONTRIBUTING Contributor onboarding - explains how to contribute to the project, follow project processes and standards, and use common tools.
CODE_OF_CONDUCT Defines expected standards of behaviour within the project community.
LICENSE Defines the legal terms under which the software can be used, modified, and distributed.
CITATION Provides instructions on how to cite the software.
AUTHORS Identifies the authors of the software (often included within a CITATION.cff file instead).
Release notes Summaries detailing new features, updates, fixes, and known issues in the latest software release.

Many of these files can be considered social documentation because they describe how people should interact with a software project and its community.

Callout

Just enough documentation

For many small projects the following three pieces of project-level documentation may be sufficient: README, LICENSE and CITATION.

Let’s look at each of these files in turn.

README file

A README file acts as the landing page for your repository and should provide enough information for users and developers to get started with your software.

To support the FAIR principles (Findability, Accessibility, Interoperability, and Reusability), certain README sections are particularly important.

Essential:

  • Purpose of the software - clearly explains what the code does; essential for findability and reusability.
  • Installation instructions - describes how to install and configure the software and its dependencies, essential for reproducibility and interoperability.
  • Usage examples - examples of how to run and use the code, helping users understand its functionality and enhancing reusability.
  • License information - links to the LICENSE file and clarifies reuse permissions, crucial for legal clarity and reusability.
  • Citation information - links to the CITATION file and explains how the software should be cited, ensuring proper attribution and reusability.

Optional:

  • Audience (who the code is intended for) - helps users identify if the code is relevant to them, improving findability and usability.
  • How to get help - informs users where they can get help, ensuring better accessibility.
  • Contribution guide - encourages and guides contributions from the community, enhancing the code’s development and maintainability.
  • FAQs - provide answers to common questions, aiding in troubleshooting and improving accessibility.
  • Code of Conduct - sets expectations for behaviour in the community, fostering a welcoming environment and enhancing accessibility.

LICENSE file

Copyright automatically applies to creative works —including software— from the moment they are created. A licence is a legal document that specifies the terms under which others may use, modify, redistribute, or build upon that work.

Because software is copyrighted by default, it is important to explicitly state the terms under which it can be reused. Without a licence, others generally have no permission to reuse the software.

The standard way to declare licensing terms is to include a file called LICENSE in the root directory of the repository.

Useful resources include:

CITATION file

A citation file provides instructions on how users should cite your software. Citation information can be provided in plain text (CITATION.txt) or Markdown (CITATION.md), but there are significant benefits to using the Citation File Format (CFF) in CITATION.cff.

CFF provides structured, machine-readable metadata that can be understood by repositories, citation services, and reference-management tools.

Why use CFF?

For developers, using a CFF file can help to automate the process of publishing new releases on Zenodo via GitHub. GitHub also “understands” CFF, and will display citation information prominently on the landing page of a repository that contains citation info in CFF.

For users, having a CITATION.cff file makes it easy to cite the software or dataset with formatted citation information available for copy+paste and direct import from GitHub into reference managers like Zotero.

CFF uses the YAML key-value pair format. At a minimum, it must contain:

  • the title of the software
  • the asset type (e.g. software or dataset)
  • at least one author

Example:

YAML 

# This CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to generate yours today!
cff-version: 1.2.0
title: My Software
message: >-
  If you use this software, please cite it using the
  metadata from this file.
type: software
authors:
  - given-names: Anne
    family-names: Researcher

Additional metadata can include abstracts, repository URLs, version information, identifiers (DOIs), and more.

A CFF file can be created or updated using the online application cffinit.

Once CITATION.cff file has been added to a repository, GitHub’s “Cite this repository” feature can generate citations in a variety of formats, including APA and BibTeX.

Summary

Software documentation helps make research software understandable, reusable, maintainable, and citable. Different forms of documentation serve different audiences. Code-level documentation supports developers and maintainers, user documentation helps people learn and use software, and project-level documentation provides essential information about the software and its community. Even small projects benefit from maintaining a README, LICENSE, and CITATION file, which together improve the discoverability, usability and reusability of software.

Key Points
  • Documentation allows users to run and understand software without having to work things out for themselves directly from the source code.
  • Different audiences (e.g. end users, developers, administrators) interact with our software in different ways and require different types of documentation.
  • Documentation can be provided at different levels
    • code-level documentation embedded within the source code to understand the implementation details,
    • software-level documentation on how to install, use, configure and modify the code,
    • project-level documentation on how to contribute to, maintain and govern the software project.
  • A (good) README, CITATION and LICENSE files are the minimum project-level documentation elements required to make research code understandable and reusable (and research it supports reproducible).
  • Documentation frameworks such as Diátaxis provide content and style guidelines that can helps us write high quality documentation.

Content from Example Code

Last updated on 2026-06-16 | Edit this page

Estimated time: 10 minutes

Overview

Questions

  • What is a minimum documentation needed for people to be able to reuse some else’s code?

Objectives

  • Obtain and run example code used for this lesson
  • List documentation types missing from the example code

For this lesson we’ll be using some example code that does spacewalks analysis available on GitHub, which we’ll clone onto our machines using the Bash shell. The spacewalks code is available from:

https://github.com/softwaresaved/spacewalks.

Obtaining Example Code

Create your own copy of the spacewalks repository above using Use this template button on GitHub.

Open a command-line shell (e.g. via Git Bash in Windows, bash shell on Linux or Terminal on a Mac) and navigate to where you would like the example code to reside (e.g. to your home directory).

Use Git to clone your copy of the spacewalks repository.

BASH 

$ cd
$ git clone https://github.com/your-repository/spacewalks.git
$ cd spacewalks

Who has successfully created a copy of the spacewalks repository in their GitHub and cloned it locally?

Examining the Code

Let’s take a look at the spacewalk analysis code, which is in the file called eva_data_analysis.py. Feel free to use your preferred editor of choice, such as Notepad, Nano or Visual Studio Code.

The code is designed to:

  • Read in the data from the JSON file
  • Change the data from one data format to another and saves to a file in the new format (CSV)
  • Perform some calculations to generate summary statistics about the data
  • Make a plot to visualise the data

A few things to note about the software project:

  • eva_data_analysis.py Python script already contains comprehensive docstrings comments
  • requirements.txt file in the project root lists the software dependencies - such as Pandas, Pytest, Matplotlib
  • data folder contains input data
  • results folder contains cleaned dataset converted to CSV format and the resulting plot
  • tests folder contains test code

Running the Example Code

Let’s run the code.

First, we will create and activate a virtual environment called “venv” from the root of the software project directory:

BASH 

$ python3 -m venv venv
$ source venv/bin/activate # Mac or Linux
$ source venv_spacewalks/Scripts/activate # Windows
(venv) $

The active virtual environment is indicated in the command line prompt between the round brackets: “(venv)”.

Next, we will install the necessary dependencies from the requirements.txt file using pip:

$ python3 -m pip install -r requirements.txt

Note: some users may be able to just use the python command instead of python3.

To ensure the code is working correctly, run the tests using Pytest.

$ python3 -m pytest

To run the analysis using the eva_data_analysis.py script from the command line terminal, do:

$ python3 eva_data_analysis.py data/eva-data.json results/eva-data.csv

If the code runs successfully, you should get the resulting plot in results/cumulative_eva_graph.png.

Who has managed to run the tests, execute the code and get some results?

Challenge

What documentation for this software is missing?

What documentation would you need to be able to run the code?

With the code provided as is (e.g. someone sent you the code via email or on a memory stick), would you be able to answer the following questions:

  • Could you run the code on your platform/operating system (is there documentation that covers installation instructions)?
  • What programs or libraries do you need to install to make it work (and which versions)?
  • Are you allowed to use this code in your own work? If you did, would the owner expect credit in some form (paper authorship, citation or acknowledgement)?
  • Are you allowed to modify the files or share them with others?
  • How easy would it be to change its parameters to calculate a different statistic, or run the analysis on a different input file?
Key Points
  • Minimum information needed to be able to run someone else code should include the reuse licence, description and purpose of the code, installation and setup instructions (including dependencies), and usage example (how to run the code).
  • Additional information may include more detailed installation guides, API documentation or design documents, list of authors and how to cite the code (this list is not exhaustive).

Content from Generating documentation with MkDocs

Last updated on 2026-06-16 | Edit this page

Estimated time: 60 minutes

Overview

Questions

  • How can we use tools like MkDocs to create documentation websites for our software?

Objectives

  • Generate and manage comprehensive software documentation using MkDocs

MkDocs documentation tool

MkDocs is a static site generator specifically designed for creating documentation websites. MkDocs can build other websites (i.e. not just documentation sites). It takes Markdown files as input and builds/outputs HTML files which you host anywhere, for example on GitHub Pages or any other website hosting platform.

mkdocs is a Python package that can be installed, for example, with pip and requires Python to run the mkdocs command. You do not need any further knowledge of Python to build your website with MkDocs after that.

By using the MkDocs tool alone, you get a relatively vanilla and straightforward website. There are additional plugins that build on top of MkDocs that provide additional functionalities to the built websites.

mkdocs-material plugin for MkDocs

“Material for MkDocs” (mkdocs-material) is a theme plugin for MkDocs that creates documentations site using a modern, responsive design. In addition to changing the look of the website, “Material for MkDocs” also enhances the functionality of websites with features like blog posts, social cards, advanced search capabilities, etc. MkDocs provides the core functionality of building a static site, while “Material for MkDocs” elevates the visual and interactive experience of your documentation.

mkdocstrings plugin for MkDocs

If you also want to automatically generate documentation from your code’s docstrings, you will need the mkdocstrings plugin. This plugin can be used with MkDocs to create documentation for software projects written in a number of programming language - as long as there is a mkdocstrings “handler” for it. Currently, there are mkdocstrings handlers for the C, Crystal, GitHub Actions, Python, MATLAB, TypeScript, and VBA languages, as well as for shell scripts. Without this plugin, core MkDocs tool only “understands” Markdown files.

Installing MkDocs & relevant plugins

Let’s install the mkdocs tool, and mkdocs-material and mkdocstrings (for Python) plugins.

Within an active virtual environment of your software project, do:

BASH 

$ python3 -m pip install mkdocs
$ python3 -m pip install "mkdocstrings[python]"
$ python3 -m pip install mkdocs-material

Who has managed to install the above 3 packages?

Generating a documentation website

Let’s create a new MkDocs site in the root of the spacewalks directory by running the mkdocs new command:

BASH 

$ mkdocs new .

OUTPUT 

INFO    -  Writing config file: ./mkdocs.yml
INFO    -  Writing initial docs: ./docs/index.md

This command creates a bunch of files:

  • docs folder in the current directory for our new MkDocs site (containing index.md file)
  • mkdocs.yml configuration file in the root of our project.

Now, let’s fill in the mkdocs.yml file with the basic configuration information for our project and mkdocs-material theme.

YAML 

site_name: Spacewalks Documentation
use_directory_urls: false
theme:
  name: "material"
  font: false

Note font: false variable is for GDPR compliance; use_directory_url: false variable tells MKDocs tools how to handle URLs for documentation that is served as a website (we will cover this in a moment).

We can run the mkdocs serve command to see what website looks like now.

BASH 

$ mkdocs serve

OUTPUT 

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.24 seconds
INFO    -  [13:59:18] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [13:59:18] Serving on http://127.0.0.1:8000/
INFO    -  [13:59:32] Browser connected: http://127.0.0.1:8000/

This command first builds the website from the files in docs folder and then serves it locally at http://127.0.0.1:8000. If you go to that URL in your browser, you can see your basic “Material for MkDocs” website.

Who has managed to build and server the website?

The “built” version of our documentation site is located in the new site folder in the root of our project. This is where MkDocs tool saves the HTML files compiled from Markdown documentation files. This directory serves as your documentation website and can be distributed together with your code. Users of your code can then read these pages locally using a Web browser. Alternatively, you can host them as a website that users can navigate to.

Note that we used the setting use_directory_urls: false in the mkdocs.yml file. This setting ensures that the documentation site is generated with URLs that are easy to navigate locally on a user’s device.

An alternative to using the mkdocs serve command is the mkdocs build command - it will only build the webpages in site folder but not serve them as a website at http://127.0.0.1:8000. You will need to re-run this command each time you make a change. To see your documentation webpages, you have to navigate directly to the site folder and open files in a Web browser.

BASH 

$ mkdocs build

Let’s add more documentation elements to our site - for example a setup guide to help users install and run the software, how to guides for common tasks and a reference manual for developers.

YAML 

site_name: Spacewalks Documentation
use_directory_urls: false
theme:
  name: "material"
  font: false
nav:
  - Home: index.md
  - Setup Guide: setup-guide.md
  - How-To Guides: how-to-guides.md
  - Reference: reference.md

Let’s create Markdown files setup-guide.md, how-to-guides.md and reference.md in docs/ folder to match our configuration.

BASH 

$ touch docs/setup-guide.md
$ touch docs/how-to-guides.md
$ touch docs/reference.md

We can add the following Markdown text to our “Setup guide”:

## Pre-requisites

Spacewalks was developed using Python version 3.12.

To install and run Spacewalks you will need have Python3 installed.
You will also need the following libraries (minimum versions in brackets):

- [NumPy](https://www.numpy.org/) >=2.0.0 - Spacewalk's test suite uses NumPy's statistical functions
- [Matplotlib](https://matplotlib.org/stable/index.html) >=3.0.0  - Spacewalks uses Matplotlib to make plots
- [pytest](https://docs.pytest.org/en/8.2.x/#) >=8.2.0  - Spacewalks uses Pytest for testing
- [pandas](https://pandas.pydata.org/) >= 2.2.0 - Spacewalks uses Pandas for data frame manipulation

## Installation instructions

Clone the Spacewalks repository to your local machine using Git.
If you don't have Git installed, you can download it from the official Git website.

`
$ git clone https://github.com/your-repository-url/spacewalks.git
$ cd spacewalks
`

Install the necessary dependencies:
`
$ python3 -m pip install -r requirements.txt
`

- To ensure everything is working correctly, run the tests using Pytest.

`
$ python3 -m pytest
`

## Usage Example

To run an analysis using the `eva_data_analysis.py` script from the command line terminal, do:

`
# Usage Examples
$ python3 eva_data_analysis.py data/eva-data.json results/eva-data.csv
`

The first argument is path to the JSON data file.
The second argument is the path the CSV output file.

If the code runs successfully, you should get the resulting plot in `results/cumulative_eva_graph.png`

Next, we can add the following Markdown text to our “How to guides”:

## How to change the file path of Spacewalk's output dataset

This guide shows you how to set the file path for Spacewalk's output data set to a location of your choice.

By default, the cleaned data set in CSV format generated by the Spacewalk software is saved to the `results/` folder within the working directory with file name `eva-data.csv`.

If you would like to modify the name or location of the output dataset, set the second command line argument to your chosen file path.
For example, if you want to save the output data set to the subfolder `data/clean/` you can invoke the script as:

`python3 eva_data_analysis.py eva-data.json data/clean/eva-data-clean.csv`

The specified destination folder `data/clean/` must exist before running spacewalks analysis script.

Finally, let’s replace the default Markdown content of the homepage of our site in index.md (which was generated by MkDocs) to include some introduction to our software and point to other documentation parts:

# Welcome to Spacewalks Documentation Site

## Overview
Spacewalks is a Python analysis tool for researchers to generate visualisations and statistical summaries of NASA's extravehicular activity datasets.

## Features
Key features of Spacewalks:

- Generates a CSV table of summary statistics of extravehicular activity crew sizes
- Generates a line plot to show the cumulative duration of space walks over time

## Documentation

You can find the following documentation:

- [Setup guide](./setup-guide.html) to help you install the software and learn how to run it
- [How to guides](./how-to-guides.html) to help you perform common tasks
- [Reference manual](./reference.html) - a full API reference

Let’s regenerate our documentation website and see what it looks like in a Web browser after these changes.

Who has managed to add the Setup and Howto guides and rebuild the website?

Generating a reference manual from dosctrings

Let’s now add support for mkdocstrings - this will allow us to automatically add docstrings from our code into our documentation using a simple tag.

YAML 

site_name: Spacewalks Documentation
use_directory_urls: false
theme:
  name: "material"
  font: false
nav:
  - Home: index.md
  - Setup Guide: setup-guide.md
  - How-To Guides: how-to-guides.md
  - Reference: reference.md

plugins:
  - mkdocstrings

Let’s populate our reference file reference.md with some preamble to include before the reference manual that will be generated from the docstrings we created.

MARKDOWN 

This file documents the key functions in the Spacewalks tool.
It is provided as a reference manual.

::: eva_data_analysis

Let’s regenerate our documentation website and see what it looks line now.

BASH 

$ mkdocs build

Who has managed to add the Reference Manual and rebuild the website?

Hosting documentation

We saw how MkDocs documentation can be distributed with our repository and viewed “offline”. We can also make our documentation available as a live website by deploying our documentation to a website hosting service.

As our repository is hosted in GitHub, we can use GitHub Pages - a free service built into GitHub that allows GitHub users to host websites directly from their GitHub repositories.

GitHub Pages deploys and serves site files from a branch - by default this is the gh-pages branch. GitHub Pages can also be configured to serve webpages from any other branch within the project repository.

Let us commit our documentation to the main branch of our Git repository and push the changes to GitHub.

BASH 

$ git add mkdocs.yml 
$ git add docs/
$ git add site/
$ git commit -m "Add project-level documentation"   
$ python3 -m pip freeze > requirements.txt
$ git add requirements.txt 
$ git commit -m "Added MkDocs tool and plugins"
$ git push origin main
Caution

Warning

Before we proceed to the next step, we must ensure that there are no uncommitted changes or untracked files in our repository.

If there are, the commands used in the upcoming steps will include them in our documentation.

BASH 

$ git status
# Add any files you want to ignore to .gitignore
# Commit .gitignore

To deploy your documentation, run the following command from the command line to deploy your documentation to GitHub.

BASH 

$ mkdocs gh-deploy

OUTPUT 

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /Users/AnnResearch/spacewalks/site
WARNING -  griffe: eva_data_analysis.py:105: No type or annotation for returned value 'int'
WARNING -  griffe: eva_data_analysis.py:84: No type or annotation for returned value 1
WARNING -  griffe: eva_data_analysis.py:33: No type or annotation for returned value 1
INFO    -  Documentation built in 0.37 seconds
WARNING -  Version check skipped: No version specified in previous deployment.
INFO    -  Copying '/Users/AnnResearcher/spacewalks/site' to 'gh-pages' branch and pushing to
           GitHub.
Enumerating objects: 63, done.
Counting objects: 100% (63/63), done.
Delta compression using up to 11 threads
Compressing objects: 100% (60/60), done.
Writing objects: 100% (63/63), 578.91 KiB | 7.93 MiB/s, done.
Total 63 (delta 7), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (7/7), done.
remote:
remote: Create a pull request for 'gh-pages' on GitHub by visiting:
remote:      https://github.com/kkh451/spacewalks/pull/new/gh-pages
remote:
To https://github.com/kkh451/spacewalks-dev.git
 * [new branch]      gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://kkh451.github.io/spacewalks/

This command will build our documentation with MkDocs, then commit and push the files to the gh-pages branch using the ghp-import tool, which is installed together with MkDocs.

For more options, use:

BASH 

$ mkdocs gh-deploy --help

Notice that the deploy command did not allow us to preview the site before it was pushed to GitHub. So, it is a good idea to build site and check it locally with the build/serve commands before deploying.

If you navigate to your software repository on GitHub, you may notice the new branch called gh-pages had been created by the mkdocs gh-deploy command and populated with the contents of your site folder.

If you navigate to “Settings/Pages” portion of your software repository, you may notice that GitHub Pages has already been configured to serve a website from your gh-pages branch. You can visit the live site by following the URL that GitHub Pages creates for your repository.

If it has not worked as described, on the “Settings/Pages” page under “Build and deployment” section you can configure the repository branch (should be gh-pages) that the GitHub Pages site is built from.

Who has managed to push the documentation website to GitHub and serve it using GitHub Pages?

Summary

We have explored the static website generator tool MkDocs for generating documentation website for our software project. mkdocs-material plugin for MkDocs creates richer and more responsive websites, while mkdocstrings plugin creates reference manuals from docstrings in our code.

Generated documentation pages can be shared with our software - they can reside in our software repository and be used by end users offline or we can use website hosting platforms such as GitHub to host documentation websites.

Key Points
  • Static site generators (such as MkDocs) can help use generate documentation websites from Markdown files or docstrings.
  • GitHub Pages provide a free webpage hosting service for your documentation website.