Practical Sphinx

Preface

Overview of chapters and major parts.

Who is this for

Who is this not for

Conventions

Author’s Note

Motivation

Make lemonade from lemons

  • Research about documentation usefulness
  • onboarding
  • project useful and used
  • reduce the frustration factor
  • write good docstrings
  • choose good names (no need to save spaces)

Minimalist Guide to Getting Started

  • quickstart
  • cookiecutter
  • fork and edit

Install

Add content

Configure

Build

Serve

Sources

What common Markup languages should I use?

  • reStructuredText
  • Markdown
  • Jupyter notebooks
  • LaTEX

How to decide whether to use reStructuredText or Markdown?

Problem

Solution

Use both.

Discussion

How do I do common formatting (bold, italics) in rst and md?

Problem

Solution

Discussion

How do I add headings of different levels?

Problem

Solution

Discussion

How do I add lists?

Problem

Solution

Discussion

How do I highlight code, filenames?

Problem

Solution

Discussion

How do I add code blocks for different programming languages?

Problem

Solution

Discussion

What is a directive? How do I add warnings boxes, tip boxes?

Problem

Solution

Discussion

I would like to include text quoted from another source. How do I do that?

Problem

Solution

Use >

Discussion

How do I use Jupyter notebooks as sources?

Problem

Solution

Discussion

nbsphinx, nbconvert

I’ve started using Markdown but now I want to switch to reStructuredText?

Problem

Solution

Discussion

recommonmark

pandoc

What is pandoc? When should I use it?

Problem

Solution

Discussion

converting sources

How do I include images?

Problem

Solution

Discussion

How do I convert images to save space and load quickly?

Problem

Solution

Discussion

imagemagick

How do I modify sources for accessibility?

Problem

Solution

Discussion

How do I modify sources for internationalization?

Problem

Solution

Discussion

Configuration

Python code

sources

parsers

theme

version

  • simple
  • _version.py

formats

  • html
  • epub
  • latex
  • man

build on RTD

custom theme

epilog

print code on pages

Extensions

Found confusing when I was getting started.

autodoc

go through the docstrings

autosummary

goes with autodoc

intersphinx

links

mathjax

equations

napoleon

docstrings

todo

not one that I use but some like it

nbsphinx

convert notebooks

write your own extensions

Themes

alabaster

sphinx_rtd_theme

built in config in conf.py

css

templates - jinja

Your own theme

Thar be dragons.

Style guide

Thursday

Mailchimp

OpenStack

Anne Gentle

Workflow

Editor

Folder structure

SHA of commit

Testing

Serve docs

APIS - Javascript and interactivity

Resources

Motivation

  • papers academic
  • jacob kaplan moss
  • anne gentle docs like code
  • eric holscher blog

Sources

  • ReadTheDocs cheatsheet
  • GitHub cheatsheet
  • rst page
  • markdown page
  • docutils

Community

ReadTheDocs

WriteTheDocs

Sphinx

Anne Gentle

Doug Hellman

Jinja

Part 1: Ideas to Documentation

Part 2: Cookbook

Part 3: Workflow

Part 4: APIs

Part 5: Continuous Improvement

Indices and tables