Sphinx-generated Github Page

This page will give a tutorial of creating Github page with sphinx supporting both reStructuredText and MarkDown markup language. See Sphinx Official Website for more detail about Sphinx

Environment Setup

Sphinx is a python based tool, all relevant installation will go through pip. In general, we need to install sphinx core, a sphinx theme, and a MarkDown parser:

$ pip install sphinx==1.5.6
$ pip install sphinx_rtd_theme
$ pip install recommonmark

Note

since recommonmark MarkDown parser has a poor support with sphinx 1.6+. Use sphinx 1.5+ before recommonmark support sphinx 1.6+

A recommended way to install these packages is putting them into a requirements.txt under docs folder of project root directory, and execute:

$ pip install -r requirements.txt

Sphinx Configuration

Initial Sphinx Set up

for initial set up of sphinx folders, execute:

$ sphinx-quickstart

this command will guide you initial set up of sphinx document source folder. Most of options can be left default, except a GithubPage option should be set to True. After finishing initial setup, open and modify conf.py.

Add build folder to gitignore

After finishing setup, some build folders should be ignored during git commit. By default, these folders are

# sphinx document build folders
path_to_sphinx_root/_build/
path_to_sphinx_root/_static/
path_to_sphinx_root/_templates/

Add Sphinx RTD theme

  1. import sphinx RTD theme library
import sphinx_rtd_theme
  1. set sphinx theme to RTD
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
  1. set sphinx theme option
html_theme_options = {
    'display_version': False,
    'navigation_depth': 2,
}

for more Sphinx rtd theme settings, see Sphinx rtd github repo

Add Sphinx MarkDown Support

  1. import markdown parser library
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
  1. Change source_suffix to following to make parser recognize markdown files
source_suffix = ['.rst', '.md']
  1. add following configuration to make use of markdown parser
source_parsers = {
    '.md': CommonMarkParser,
}

def setup(app):
    app.add_config_value('recommonmark_config', {
        'enable_eval_rst': True,
    }, True)
    app.add_transform(AutoStructify)

if you want to modify setup of recommonmark markdown parser, refer to Recommonmark Documentation

Index.rst setup

Although recommonmark support sphinx markdown parsing, it still lack of some functionality. One of them is toctree which allow you to see documentation structure on the left-hand side of webpage. To enable toctree, we need to write index file in rst format. The index.rst will contain only documentation title (automatically generated during initial setup) and files need to contain in the toctree sections. a sample format is as below

.. toctree::
   :glob:
   :caption: section title

   docsFolderName/*
   docFileName1.md
   docFileName2.rst

As code sample above, document files can be found with regular express pattern matching. This is accomplished by :glob: attribute. It avoids adding document file name to index every time a new file is created, but files that failed in pattern matching still need to be added manually. For more information of how to write toctree, see Sphinx TOC tree Docs

Write Documentation

Generally, writing rst format documents is recommended for sphinx. If you want still using markdown. Following some rules to make sphinx parser generate toctree correctly.

  1. Every Document Starts with #, a title for this documentation
  2. Use ## for subsection, use ### as further section division
  3. If document contains table, you may want to swtich to rst (current sphinx markdown parser doesn’t support table parsing), see rst reference to know how to write reStructuredTest Document.

Note

you may not use github wiki page editor preview to determine which markdown # title level you should use, since github will render major # header really large.

After creating a document, make sure your new document file name is in index.rst or satisfying any pattern matching in any toctree section. Otherwise, readers are not able to navigate to your page (In order word, your documents are useless)

Locally View Documentation

Before pushing your documents to repository, viewing them locally to make sure it displays as expected and check no any typo. To do so, simply execute following command in sphinx root directory (not project root directory)

$ make html

if you didn’t change settings during initial setup, a folder named _build will show up, inside this folder, there is a html folder. Open index.html and you should be able to view documentation webpage locally.

Note

When you modify some files and rebuild documentation page, but didn’t see any changes, clean temperary build files by running

$ make clean

Deploy to Github Page

Since obtaining Sphinx Documentation requires a build step, there are two ways to deploy built sphinx page to Github page. One is using some automatic built services (like Travis-CI) which will automatically build and deploy for you. The other is built locally yourself.

Deploy with Travis-CI

Deploy with Travis-CI basically needs 4 steps:

  1. modify .travis.yml configuration by adding the following (only works in python environment). For more information about travis github page deployment, see Travis Configuration
install:            # Install requirement as "Environment Setup Section"
- pip install -r sphinx_root/requirements.txt
script:             # build sphinx document
- cd sphinx_root/
- make html
- cd -
deploy              # deploy to github page
- provider: pages
  skip_cleanup: true
  local_dir: sphinx_root/_build/html
  github_token: $GITHUB_TOKEN # Set in travis-ci.org dashboard
  1. Obtain Github personal token. This Token can be anyone who has access right to Repository. To obtain this token, Go to personal Github settings, At very end of left column, click personal access tokens and create a new one. With regards to Scope option during token creation, only public_repo should be selected for safety. Put this token in Travis-CI environment variable settings with name corresponding to travis script

Note

Whoever use their own personal access token, every auto deployment commit will be treated as their commit. For a team, it’s recommended to use tokens from organization

  1. Change repository settings repository manager should change github page source to branch gh-pages branch. This branch will be created during auto deployment by default.

Note

gh-pages branch can’t be a protected branch, otherwise, Travis-CI won’t be able to push to repository.

Locally built and deploy by push

Deploy by github push needs 6 steps:

  1. create a source directory inside docs folder of repo root directory and move everything in sphinx root to new folder
  2. allow git to track sphinx temp file by removing these lines shown gitignore section
  3. Change Sphinx build path to parent directory of sphinx root directory by changing two lines in Makefile and make.bat:
# in Makefile
BUILDDIR=_build        ->       BUILDDIR=..
# in make.bat
set BUILDDIR=_build    ->       set BUILDDIR=..
  1. execute following command to move files to docs folder in root docs directory
$ mv html/* ./

Note

if this command reports error, there are several possibilities:

  1. didn’t build document with make html
  2. execute in wrong directory.
  3. may need to clean the root docs directory, only leave source folder there and html folder there
  1. commit every change in docs folder and push it to github
  2. (only needs to be done once) change github repo github page settings, make source to be master branch /docs folder