This lesson is still being designed and assembled (Pre-Alpha version)

Building Documentation with Sphinx

Overview

Teaching: 0 min
Exercises: 0 min
Questions
  • How can I make my documentation more accessible

Objectives
  • Build a documentation website with sphinx

  • Add overview documentation

  • Distribute a sphinx documentation site

Sphinx is a tool for building documentation.

What does sphinx produce?

Exercise

In a group, have each member open one of the following packages’ documentation

Discuss what the common components are, what is helpful about these documentation sites, how they address the general concepts on documentation, how they’re similar and how they’re different.

Solution

these all use sphinx to generate them?

Sphinx quicksetup

FIXME: guide through setup and what options mean

Adding literal documentation

FIXME: RST overview

FIXME: adding pages

API Documentation

Add an api line to the indnex.rst so that it has a link to it.

The create an API.rst file:

API documentation
==================


Key Points

  • Building documentation into a website is a common way of distributing it

  • Sphinx will auto build a website from plain text files and your docstrings