Daniel's blogs
0%

01-sphinx : basic demo

Posted on Edited on In , Disqus:

Install sphinx and sphinx-rtd-theme

1
2
3
4
5
6
workon py3dev 

pip install sphinx
pip install sphinx-rtd-theme

pip list

Init a project with sphinx.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
mkdir sphinx_demo

cd sphinx_demo
sphinx-quickstart

# Choose seprate source and builder, for other configuration, choose whatever you want.

mkdir src

tree -L 1

.
├── Makefile	# build script for Unix.
├── build 		# sphinx docs build result.
├── make.bat	# build script for windows os.
├── source		# source folder for sphinx docs.
└── src 		# user defined folder for python modules and scripts.

Config sphinx.

Edit source/conf.py

Set python source folder.

1
2
3
4
5
# add those lines.
import os
import sys

sys.path.insert(0, os.path.abspath('../src/'))

Enable autodoc plugins.

1
2
3
extensions = [
    'sphinx.ext.autodoc'
]

Enable read-the-doc theme.

1
html_theme = 'sphinx_rtd_theme'

Build sphinx docs.

1
2
3
make html 	# build the docs by html builder.

open build/html/index.html