sphinx 简明教程

这篇快速介绍如何使用sphinx来创建文档

安装

pip install sphinx

使用

一般情况下应在目录下创建docs文件夹，然后使用sphinx-quickstart
来调用生成模板，之后有一堆英文配置，其中要注意的是source,build是否分离，一般是要选y的，还有就是如果是中文语言要配置成zh_CN
.之后生成的文件结构类似于如下的目录。

.
├── Makefile
├── build
├── make.bat
└── source
   ├── _static
   ├── _templates
   ├── conf.py
   └── index.rst

conf是相关的配置，Makefile是生成的编译脚本，之后输入make html，会生成相应的文档。

.
├── Makefile
├── build
│   ├── doctrees
│   │   ├── environment.pickle
│   │   └── index.doctree
│   └── html
│       ├── _sources
│       │   └── index.rst.txt
│       ├── _static
│       │   ├── ajax-loader.gif
│       │   ├── alabaster.css
│       │   ├── basic.css
│       │   ├── comment-bright.png
│       │   ├── comment-close.png
│       │   ├── comment.png
│       │   ├── custom.css
│       │   ├── doctools.js
│       │   ├── documentation_options.js
│       │   ├── down-pressed.png
│       │   ├── down.png
│       │   ├── file.png
│       │   ├── jquery-3.2.1.js
│       │   ├── jquery.js
│       │   ├── minus.png
│       │   ├── plus.png
│       │   ├── pygments.css
│       │   ├── searchtools.js
│       │   ├── underscore-1.3.1.js
│       │   ├── underscore.js
│       │   ├── up-pressed.png
│       │   ├── up.png
│       │   └── websupport.js
│       ├── genindex.html
│       ├── index.html
│       ├── objects.inv
│       ├── search.html
│       └── searchindex.js
├── make.bat
└── source
   ├── _static
   ├── _templates
   ├── conf.py
   └── index.rst

生成的内容在build/html
目录下，可以使用python -m http.server
来启动一个http的server来访问。

内容形态

默认只生成了index.rst
, 默认生成的内容如下，

.. test documentation master file, created by
  sphinx-quickstart on Thu Nov  8 22:18:23 2018.
  You can adapt this file completely to your liking, but it should at least
  contain the root `toctree` directive.

Welcome to test's documentation!
================================

.. toctree::
  :maxdepth: 2
  :caption: Contents:



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

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

每一个rst文档，都要有对应的标题，比如可以用文字下的=======
来表示, 具体的请参考rst格式相关的文档。

插入子页面并添加至目录

下面介绍如何插入一个子文档，并生成目录。

.. toctree::
   a.rst
   b.rst

这样会在index页面的标题中插入a和b两个链接，而我们需要编辑a.rst和b.rst两个文件。

比如可以在a.rst中可以编辑

帮助
====

帮助的话也请联系pingf0@gmail.com哈

这里面标题是必须的，而在index目录中显示的也是这里的标题而不是a.rst.

插入一段代码

.. code::
   if __name__ == '__main__':
      print("hello world")

自动生成文档

以termcc为例termcc和docs在同级别目录, 需要再conf.py
中配置相对path，因为当前index.rst
在docs/source
目录下

import os
import sys
sys.path.insert(, os.path.abspath('../../'))

另外conf.py
中的extension要配置如下

extensions = [
   'sphinx.ext.autodoc',
   'sphinx.ext.autosummary'
]

然后文档中插入

.. autosummary::

  termcc.cc
  termcc.core
  termcc.unicodes_codec

比如在指定的term.cc中，如果有

"""
this is the doc
"""

这样的字串，将会被自动加载进来。

另外也可以使用.. currentmodule:: termcc
来配置自动插入module。

更漂亮的主题

执行pip install sphinx_rtd_theme
, 并在conf.py
中配置

html_theme = 'sphinx_rtd_theme'

发布

直接push到github，然后通过read the doc官方绑定并编译即可

来源 https://www.modb.pro/db/210910