Sphinx一分钟上手

1. 安装Sphinx

pip install Sphinx

2. 创建文档路径

mkdir docs
cd docs

3. quickstart

sphinx-quickstart

4. 修改conf.py

4.1 配置路径至项目根路径

4.2 根据需要配置conf.py/extensions

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

4.3 根据需要配置conf.py/latex

5. 配置修改index.rst相关文件

index.rst

Documentation for the Code
**************************
.. toctree::
   :maxdepth: 2
   :caption: Contents:

TeacherAPI main
===================
.. automodule:: app
   :members:

TeacherAPI controller
=====================
.. automodule:: teacherAPI.controller
   :members:

TeacherAPI models
=================
.. automodule:: teacherAPI.models
   :members:

TeacherAPI database
===================
.. automodule:: teacherAPI.database
   :members:

TeacherAPI populate
===================
.. automodule:: teacherAPI.populate
   :members:

6. 创建HTML和PDF文档

make html
sphinx-build -b rinoh source _build/rinoh

保证在docs文档目录下

个人实践

conf.py

html_theme = 'bizstyle'
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx.ext.coverage', 'sphinx.ext.napoleon']

project = 'nlp_server'
copyright = '2019, Scott'
author = 'Scott'

language = 'zh_CN'

html_theme = 'bizstyle'

index.rst

Welcome to nlp_server's documentation!
======================================

.. toctree::
   :maxdepth: 3
   :caption: Contents:

   full_kid
   extractor
   asr

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

full_kid.rst

Welcome to full_kid's documentation!
======================================
.. automodule:: full_kid.data_aggregate
   :members:

.. automodule:: full_kid.db_process
   :members:

进阶可参阅：
Documenting Your Project Using Sphinx
Brandon’s Sphinx Tutorial–更深入的教程
Overview — Sphinx 1.8.0+ documentation

翻译自A Simple Tutorial on How to document your Python Project using Sphinx and Rinohtype