Initial Sphinx Set up¶

for initial set up of sphinx folders, execute:

(sphinx)$ 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.

Add some 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/

After finishing initial setup, open and modify conf.py.

Add not sphinx builtin themes if necessary¶

1. for example, import Flask sphinx theme library

import Flask-Sphinx-Themes

2. set sphinx theme to Flask

html_theme = "Flask-Sphinx-Themes"
html_theme_path = [Flask-Sphinx-Themes.get_html_theme_path()]

3. set sphinx theme option

html_theme_options = {
    'github_ribbon_color': darkblue_121621,
}

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

Add Sphinx MarkDown Support¶

1. import markdown parser library

from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify

2. Change source_suffix to following to make parser recognize markdown files

source_suffix = ['.rst', '.md']

3. 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

   docs_folder_name/*
   doc_file_name1.md
   doc_file_name2.rst

As code sample above, document files can be found with regular expression 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

First option: Deploy by git-simple¶

You can deploy easily your gh-pages docs using gpublish command from git-simple You only need to install git-simple shell scripts (very easy and clean)

Second option: 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=..

4. execute following command to move files to docs folder in root docs directory

$ mv html/* ./

5. commit every change in docs folder and push it to github
6. (only needs to be done once) change github repo github page settings, make source to be master branch /docs folder

Third option: 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

2. 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

3. 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.