# Sphinx Documentation

### Why?

Sphinx is a great tool for documenting Python, but its remarkably difficult to get started with, and (oddly enough) hard to find a good beginner’s tutorial for.

## Getting Started

Run sphinx-quickstart, which will start you through the process, and interactively ask you questions, and make a docs/conf.py and a docs/Makefile for you. I don’t remember how I answered the questions.

## Organization

I like to put docs in a docs folder, which is then where sphinx-quickstart will create a configuration file named conf.py and a Makefile. Then I like to have something like the following:

{package-folder}
|- docs
|- conf.py
|- index.rst


### Readme file: README.rst

This is a standard README, that will appear on the Github page and in the documentation index file.

It should have a few sections:

• Description
• Installation
• Example usage

### Index file: docs/index.rst

This is the “welcome page”. It has two parts: the introduction (sourced from README.rst), and the Table of Contents. Here is source for it:

This will include the README from above, and add links to docs/example-usage.rst (make that yourself) and docs/api.rst (see below).

### API file: docs/api.rst

This will tell Sphinx to auto-generate documentation from the module.

## Generating documentation

Or for more options, make help.