How to Contribute to a Sphinx Doc Documentation Release 1.0 Haoxi Zhan December 18, 2013
Contents 1 Install Sphinx 3 1.1 Linux................................................... 3 1.2 Mac OS X................................................ 3 1.3 Windows................................................. 4 2 Start a Sphinx Project 5 2.1 Create a directory............................................ 5 2.2 Start a project............................................... 5 3 Configure Your Project 9 3.1 Themes.................................................. 9 3.2 Logo................................................... 9 3.3 Highlight................................................. 9 4 Write Docs 11 4.1 Write with restructuredtext....................................... 11 4.2 index.rst................................................. 11 4.3 Insert Codes............................................... 11 4.4 Insert images............................................... 13 4.5 Insert Math................................................ 13 5 Build and Publish 15 5.1 Build to HTML.............................................. 15 5.2 Build to epub............................................... 15 5.3 Build to LaTeX and PDF......................................... 15 5.4 Build and Publish on ReadTheDocs................................... 15 i
ii
Note: This doc is created only as an experiment. The content is not mature. Contents: Contents 1
2 Contents
CHAPTER 1 Install Sphinx This chapter introduces how to install Sphinx on your computer. Sphinx is a documentation tool wrote in Python. So it is cross-platform. 1.1 Linux Most linux distributions already have Sphinx in their office repos. All you need to do is to use the official package manager to install it. However, you need to make sure you installed the right Sphinx as there s a few other packages called sphinx. This is a list of names of the Sphinx package in most mainstream Linux distributions: Ubuntu Fedora Mageia Archlinux Distribution open- SUSE Debian Python2 package python- Sphinx pythonsphinx pythonsphinx pythonsphinx pythonsphinx python2- sphinx Python3 package python3- Sphinx python3- sphinx python3- sphinx python3- sphinx None pythonsphinx Install Command 1 zypper in python3-sphinx apt-get install python3-sphinx apt-get install python3-sphinx yum install python3-sphinx urpmi python-sphinx pacman -S python-sphinx 1.2 Mac OS X Sphinx is available in MacPorts. There are a lot of choices provided for different Python versions. 1 I assume that you are willing to install the Python3 version if available. I don t include sudo or su here. 3
1.3 Windows 2 You could install Sphinx via easy_install. 2 Although I introduced how to install Sphinx in Windows, other parts in this HOWTO would strongly bias toward Unix-like systems. 4 Chapter 1. Install Sphinx
CHAPTER 2 Start a Sphinx Project This chapter introduces how to start a new Sphinx project. If you just want to contribute to an existing document, there s no need for you to read this chapter. 2.1 Create a directory You need a directory for your Sphinx project. It is supposed that the location of your working directory contains only English characters and numbers. As far as I know, Asian characters are not supported. However, any UTF-8 characters are supported in ReST contents. 2.2 Start a project Then you can start a project by running: sphinx-quickstart The program would ask you a series of question. If you want to use the default value, you could simply type Enter. 2.2.1 > Root path for the documentation [.] This question asks you the root path for your document. The default value is., which means the current directory. 2.2.2 > Separate source and build directories (y/n) [n] This question asks you whether you want to separate your source codes and build results. The default value is no. Some people might prefer them to be separated. 2.2.3 > Name prefix for templates and static dir [_]: This question asks you the prefix for static directories. For example, the directory to place build results would be _build if you choose _ as the prefix. The default value is _ and there s no need to choose another one. 5
2.2.4 > Project name: Project name. 2.2.5 > Author name(s): Author name(s). This would be shown in the copyright information. 2.2.6 > Project version: Version of your project. Sphinx assumes that you are documenting to a software. If so, you could type the version of your software here. If you are writing something else, you could choose any version number you like. 2.2.7 > Project release [$version] Sphinx allow you to create different releases for each version. The default value is the version number you just typed in. If you don t need this feature, you could use the default value. 2.2.8 > Source file suffix [.rst] Only files with this suffix would be considered as your contents. Normally, ReStructuredText sources have the suffix.rst. You could also choose.txt. But if you choose.txt,.rst files would not be compiled. 2.2.9 > Name of your master document (without suffix) [index]: The master document is the one which would become the homepage. Normally, use index, which is the default value. 2.2.10 > Do you want to use the epub builder (y/n) [n]: Sphinx could compile your docs into epub books. However, answering n here would not prevent you from compiling epubs in the future. 2.2.11 > autodoc: automatically insert docstrings from modules (y/n) [n]: This is for Python-related projects. 2.2.12 > doctest: automatically test code snippets in doctest blocks (y/n) [n]: This is for Python-related projects. 2.2.13 > intersphinx: link between Sphinx documentation of different projects (y/n) [n]: Enabling this extension would allow you to link between different Sphinx projects. 6 Chapter 2. Start a Sphinx Project
2.2.14 > todo: write todo entries that can be shown or hidden on build (y/n) [n]: This extension would allow you to write some TODOs in your doc. When you build your doc, you could choose to hide them. 2.2.15 > coverage: checks for documentation coverage (y/n) [n]: I don t know what it is:-) 2.2.16 > pngmath: include math, rendered as PNG images (y/n) [n]: This extension would render your math formulas to PNG images. This is not recommended because there s MathJax. 2.2.17 > mathjax: include math, rendered in the browser by MathJax (y/n) [n]: If you need to render math formulas, I suggest you to choose this extension instead of pngmath. 2.2.18 > ifconfig: conditional inclusion of content based on config values (y/n) [n]: This extension provides some control flow for your documents. Usually it would not be needed. 2.2.19 > viewcode: include links to the source code of documented Python objects (y/n) [n]: This is for Python-related projects. 2.2.20 > Create Makefile? (Y/n) [y]: Strongly recommend. This extension would create a UNIX Makefile for you to build the doc. 2.2.21 > Create Windows command file? (Y/n) [y]: Similar to the item above but for Windows. If there are Windows users among your team, it is suggested. After answering all these questions, a new Sphinx project would be created. Then we are going to configure it. 2.2. Start a project 7
8 Chapter 2. Start a Sphinx Project
CHAPTER 3 Configure Your Project So far, we have created a project. Now we are going to configure it. All the configurations in this chapter are inside conf.py. 3.1 Themes The default theme is ugly. Sphinx provides some better themes. Personally, I like sphinxdoc, agogo, haiku and pyramid. This document uses pyramid. Besides that, there s a lot of others themes available on the Internet. Readthedocs provides a theme and there s also one for Mozilla Developer Network. # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = pyramid 3.2 Logo There s also a feature to add a logo for your doc: # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None 3.3 Highlight If all your code blocks in the project would be the same programming language, you could add a line in conf.py to specify this language. Here s an example: highlight_language = ocaml After adding this line, you would no longer need to specify the language to highlight. All code blocks in the project would be highlighted as OCaml. 9
10 Chapter 3. Configure Your Project
CHAPTER 4 Write Docs 4.1 Write with restructuredtext restructuredtext Primer is a very good tutorial. 4.2 index.rst As Sphinx is primarily designed for documenting Python packages, if you are using it to do other things, you might need to edit the main page. It is also a ReST source file so there s no essential difference between index.rst and other source files. However, there s a toctree directive. In toctree, you need to indicate what ReST files you need in the table of contents. Then toctree would automatically generate the table of contents. maxdepth option is used to define the depth of the TOC. 4.3 Insert Codes If you ve chosen a highlighting language in conf.py, all you need to use is ::. Example: This is a code block:: qsort2 :: (Ord a) => [a] -> [a] qsort2 [] = [] qsort2 (a:xs) = qsort ls ++ a:(qsort ms) where (ls,ms) = partition (< a) xs If you didn t, you could specify it in files to gain more flexibility. highlight directive provides an automatic highlighting feature. By using it, all your code-block directives could be simplified to ::. After using it, the settings would be used until the next highlight directive appears. 11
4.3.1 highlight directive.. highlight:: haskell This would set the highlighting language to be Haskell... highlight:: haskell :linenothreshold: 5 This would set a threshold for automatic line-numbering feature. 4.3.2 code-block directive It is the most flexible one. But you would need to specify the language before every code block... code-block:: haskell would generate: qsort2 :: (Ord a) => [a] -> [a] qsort2 [] = [] qsort2 (a:xs) = qsort ls ++ a:(qsort ms) where (ls,ms) = partition (< a) xs qsort2 :: (Ord a) => [a] -> [a] qsort2 [] = [] qsort2 (a:xs) = qsort ls ++ a:(qsort ms) where (ls,ms) = partition (< a) xs.. code-block:: haskell :linenos: would generate: qsort2 :: (Ord a) => [a] -> [a] qsort2 [] = [] qsort2 (a:xs) = qsort ls ++ a:(qsort ms) where (ls,ms) = partition (< a) xs 1 qsort2 :: (Ord a) => [a] -> [a] 2 qsort2 [] = [] 3 qsort2 (a:xs) = qsort ls ++ a:(qsort ms) 4 where (ls,ms) = partition (< a) xs.. code-block:: haskell :linenos: :emphasize-lines: 1,3 would generate: qsort2 :: (Ord a) => [a] -> [a] qsort2 [] = [] qsort2 (a:xs) = qsort ls ++ a:(qsort ms) where (ls,ms) = partition (< a) xs 1 qsort2 :: (Ord a) => [a] -> [a] 2 qsort2 [] = [] 3 qsort2 (a:xs) = qsort ls ++ a:(qsort ms) 4 where (ls,ms) = partition (< a) xs 12 Chapter 4. Write Docs
4.3.3 Include source files Example: 1.. literalinclude:: example.clj 2 :language: clojure 3 :linenos: 4 :emphasize-lines: 2,9,13-15 The file name is relative to the path of the rst file. But you can also use an absolute path which is actually relative to the root of the project directory. Such a path would be similar to /code/example.clj. 4.4 Insert images.. image:: linux.png This would insert a PNG image in the page. Again, you are free to choose to use relative pathes (relative to the location of the rst file) or absolute pathes. 4.5 Insert Math There are some examples for inserting math formulas and graphes in the official site of Sphinx. 4.4. Insert images 13
14 Chapter 4. Write Docs
CHAPTER 5 Build and Publish 5.1 Build to HTML make html 5.2 Build to epub make epub 5.3 Build to LaTeX and PDF make latex would build the project to a LaTeX file. make latexpdf would build your project to PDF via LaTeX tool chains. 5.4 Build and Publish on ReadTheDocs Read the Docs is an online service which builds and publishes Sphinx docs online for free. At first, you need to register. Then: 1. Click Dashboard 2. Click create new docs 3. Fill in all required (bold) fields 4. Click Create Now you have created your ReadtheDocs project and RTD would automatically build your project. 15
5.4.1 Enable the Hook Github and BitBucket both provide a feature called Hook. Once you pushed new commits to a repo, they would automatically transmit your new commits to Read the Docs. So after you ve created your project in Read the Docs, you are supposed to enable the hook in your repo. 16 Chapter 5. Build and Publish