The RestructuredText Book Documentation Release 1.0 Daniel Greenfeld, Eric Holscher Sep 05, 2018 Tutorial 1 Schedule 2 1.1 Getting Started: Overview & Installing Initial Project................2 1.2 Step 1: Getting started with RST...........................8 1.3 Step 2: Building References & API docs...................... 13 1.4 Step 3: Keeping Documentation Up to Date..................... 23 1.5 Finishing Up: Additional Extensions & Individual Exploration........... 27 1.6 Cheat Sheet...................................... 31 1.7 Crawler Step 1 Documentation........................... 34 1.8 Crawler Step 2 Documentation........................... 34 1.9 Crawler Step 3 Documentation........................... 36 Python Module Index 40 i The RestructuredText Book Documentation, Release 1.0 Welcome to the Introduction to Sphinx & Read the Docs. This tutorial will walk you through the initial steps writing reStructuredText and Sphinx, and deploying that code to Read the Docs. Please provide feedback to @ericholscher. Tutorial 1 Chapter 1 Schedule • 9-9:30 Introduction to the Tutorial • 9:30-9:50 Getting Started: Overview & Installing Initial Project • 9:50-10:20 Step 1: Getting started with RST • 10:20-10:40 Break • 10:40-11:10 Step 2: Building References & API docs • 11:10-11:40 Step 3: Keeping Documentation Up to Date • 11:40-12:20 Finishing Up: Additional Extensions & Individual Exploration Thanks for coming 1.1 Getting Started: Overview & Installing Initial Project 1.1.1 Concepts Sphinx Philosophy Sphinx is what is called a documentation generator. This means that it takes a bunch of source files in plain text, and generates a bunch of other awesome things, mainly HTML. For our use case you can think of it as a program that takes in plain text files in reStructuredText format, and outputs HTML. reST-> Sphinx-> HTML 2 The RestructuredText Book Documentation, Release 1.0 So as a user of Sphinx, your main job will be writing these text files. This means that you should be minimally familiar with reStructuredText as a language. It’s similar to Markdown in a lot of ways, if you are already familiar with Markdown. 1.1.2 Tasks Installing Sphinx The first step is installing Sphinx. Sphinx is a python project, so it can be installed like any other python library. Every Operating System should have Python pre-installed, so you should just have to run: pip install sphinx Note: Advanced users can install this in a virtualenv if they wish. Also, easy_install install Sphinx works fine if you don’t have pip. Get this repo To do this tutorial, you need the actual repository. It contains the example code that we will be documenting. You can clone it here: git clone https://github.com/ericholscher/pycon-sphinx-tutorial Getting Started Now you are ready to start creating documentation. You should have a directory called crawler, which contains source code in it’s src directory. Inside the crawler you should create a docs directory, and move into it: cd crawler mkdir docs cd docs Then you can create the Sphinx project skeleton in this directory: sphinx-quickstart 1.1. Getting Started: Overview & Installing Initial Project 3 The RestructuredText Book Documentation, Release 1.0 Have the Project name be Crawler, put in your own Author name, and put in 1.0 as the Project version. Otherwise you can accept the default options. My output looks like this: 1 -> sphinx-quickstart 2 Welcome to the Sphinx 1.3.1 quickstart utility. 3 4 Please enter values for the following settings (just press Enter to 5 accept a default value, if one is given in brackets). 6 7 Enter the root path for documentation. 8 > Root path for the documentation [.]: 9 10 You have two options for placing the build directory for Sphinx output. 11 Either, you use a directory "_build" within the root path, or you ,!separate 12 "source" and "build" directories within the root path. 13 > Separate source and build directories (y/n) [n]: 14 15 Inside the root directory, two more directories will be created; "_ ,!templates" 16 for custom HTML templates and "_static" for custom stylesheets and ,!other static 17 files. You can enter another prefix (such as ".") to replace the ,!underscore. 18 > Name prefix for templates and static dir [_]: 19 20 The project name will occur in several places in the built ,!documentation. 21 > Project name: Crawler 22 > Author name(s): Eric Holscher 23 24 Sphinx has the notion of a "version" and a "release" for the 25 software. Each version can have multiple releases. For example, for 26 Python the version is something like 2.5 or 3.0, while the release is 27 something like 2.5.1 or 3.0a1. If you don't need this dual structure, 28 just set both to the same value. 29 > Project version: 1.0 30 > Project release [1.0]: 31 32 If the documents are to be written in a language other than English, 33 you can select a language here by its language code. Sphinx will then 34 translate text that it generates into that language. 35 36 For a list of supported codes, see 37 http://sphinx-doc.org/config.html#confval-language. (continues on next page) 1.1. Getting Started: Overview & Installing Initial Project 4 The RestructuredText Book Documentation, Release 1.0 (continued from previous page) 38 > Project language [en]: 39 40 The file name suffix for source files. Commonly, this is either ".txt" 41 or ".rst". Only files with this suffix are considered documents. 42 > Source file suffix [.rst]: 43 44 One document is special in that it is considered the top node of the 45 "contents tree", that is, it is the root of the hierarchical structure 46 of the documents. Normally, this is "index", but if your "index" 47 document is a custom template, you can also set this to another ,!filename. 48 > Name of your master document (without suffix) [index]: 49 50 Sphinx can also add configuration for epub output: 51 > Do you want to use the epub builder (y/n) [n]: 52 53 Please indicate if you want to use one of the following Sphinx ,!extensions: 54 > autodoc: automatically insert docstrings from modules (y/n) [n]: 55 > doctest: automatically test code snippets in doctest blocks (y/n) ,![n]: 56 > intersphinx: link between Sphinx documentation of different projects ,!(y/n) [n]: 57 > todo: write "todo" entries that can be shown or hidden on build (y/ ,!n) [n]: 58 > coverage: checks for documentation coverage (y/n) [n]: 59 > pngmath: include math, rendered as PNG images (y/n) [n]: 60 > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 61 > ifconfig: conditional inclusion of content based on config values (y/ ,!n) [n]: 62 > viewcode: include links to the source code of documented Python ,!objects (y/n) [n]: 63 64 A Makefile and a Windows command file can be generated for you so that ,!you 65 only have to run e.g. `make html' instead of invoking sphinx-build 66 directly. 67 > Create Makefile? (y/n) [y]: 68 > Create Windows command file? (y/n) [y]: 69 70 Creating file ./conf.py. 71 Creating file ./index.rst. 72 Creating file ./Makefile. 73 Creating file ./make.bat. 74 (continues on next page) 1.1. Getting Started: Overview & Installing Initial Project 5 The RestructuredText Book Documentation, Release 1.0 (continued from previous page) 75 Finished: An initial directory structure has been created. 76 77 You should now populate your master file ./index.rst and create other ,!documentation 78 source files. Use the Makefile to build the docs, like so: 79 make builder 80 where "builder" is one of the supported builders, e.g. html, latex or ,!linkcheck. Your file system should now look similar to this: crawler src docs index.rst conf.py Makefile make.bat _build _static _templates We have a top-level docs directory in the main project directory. Inside of this is: index.rst: This is the index file for the documentation, or what lives at /. It normally contains a Table of Contents that will link to all other pages of the documentation. conf.py: Allows for customization of Sphinx. You won’t need to use this too much yet, but it’s good to be familiar with this file. Makefile & make.bat: This is the main interface for local development, and shouldn’t be changed. _build: The directory that your output files go into. _static: The directory to include all your static files, like images. _templates: Allows you to override Sphinx templates to customize look and feel. Building docs Let’s build our docs into HTML to see how it works. Simply run: # Inside top-level docs/ directory. make html This should run Sphinx in your shell, and output HTML. At the end, it should say something about the documents being ready in _build/html. You can now open them in your browser by typing: 1.1. Getting Started: Overview & Installing Initial Project 6 The RestructuredText Book Documentation, Release 1.0 # On OS X open _build/html/index.html You can also view it by running a web server in that directory: # Inside docs/_build/html directory. python-m SimpleHTTPServer # For python 3 python3-m http.server Then open your browser to http://localhost:8000. This should display a rendered HTML page that says Welcome to Crawler’s documentation! at the top. Note: make html is the main way you will build HTML documentation locally. It is simply a wrapper around a more complex call to Sphinx, which you can see as the first line of output. Custom Theme You’ll notice your docs look a bit different than mine. First, you need to install the theme: $ pip install sphinx_rtd_theme Then you need to update a few settings in your conf.py.