安装
pip install sphinx
假设现在我们有一个叫run.py的文件,如下
# run.py
def run(name):
"""
this is how we run
:param name name of people who runs
"""
print name, 'is running'
- 创建一个文件夹demo/,并将run.py放到里面
- 在demo里创建一个docs目录,进入docs/目录,当然这里你可以随意选定文件夹,只是这样更规范一些
- 运行sphinx-quickstart , 生成Sphinx默认模板,设置项目名为demo,并开启autodoc
- 进入source目录,打开index.rst
- 将index.rst 修改为如下,实际上这里面可以写任何满足rst规范的内容
.. toctree::
:maxdepth: 2
:caption: Contents:
Introduction
============
This is the introduction of demo。
API
===
.. automodule:: run
:members:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
将demo目录加入sys.path,所以现在打开conf.py,添加如下内容
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
运行Sphinx生成html文档
sphinx-build -b html source build
make html
打开build/html/index.html就可以看到如下界面了