用 Sphinx 写文档

内容简介：用 Sphinx 写文档

用 Sphinx 写文档

[TOC]

本文记录使用 Sphinx 写文档，以及利用Nginx 完成部署的整个过程。

环境

Sphinx 本身是使用 Python 写的，所以你需要Python 的环境。由于我在Ubuntu14.04 下自然不用操心这个问题，如果是在Windows 环境下我没试过。

• 安装Sphinx

  pip install Sphinx

  `
• 扩展安装 Sphinx 有个很强大扩展能力， 官网 给出了很多. 实在不满意还可以 自己定制 除非是对外文档，我想不需要这么炫的功能。有基本的完全满足需求。 Sphinx 默认是不产生侧边栏的Tree 结构的，所以找了个插件 sphinxcontrib-fulltoc

  pip install sphinxcontrib-fulltoc

  在里文档项目路径下运行下面的命令，我的在``

  test-doc``` 目录下。

StartProject

sphinx-quickstart

完了之后会在当前路径下产生一些文件，之所以是在当前路径下，是以为我上面选择的是当前路径，仔细看上图。 ``` . ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├── index.rst ├── static └── templates

```

配置

扩展

source 路径是存放文档原文件的地方，

conf.py

是配置文件，能设置主题，扩展等。
现在就把插件添加进去，打开conf.py 添加最后一项，其他的都是在上面选择的时候产生的，我基本选择的是yes ,所以会比较多
``

extensions = [ 33 'sphinx.ext.autodoc', 34 'sphinx.ext.doctest', 35 'sphinx.ext.intersphinx', 36 'sphinx.ext.todo', 37 'sphinx.ext.coverage', 38 'sphinx.ext.mathjax', 39 'sphinx.ext.ifconfig', 40 'sphinx.ext.viewcode', 41 'sphinx.ext.githubpages', 42 'sphinxcontrib.fulltoc', 43 ]

```

主题

Sphinx 提供很多主题，去 官网 选择，你会发现很多主题都是很熟悉，如果你用Python 的化。默认是使用 Flask 一样的主题 打开

conf.py

下面的位置可以编辑主题
``

语法

Sphinx 的文档默认是

.rst

文件，语法和Markdown 类似，但是我感觉某些地方会比较有优势
找了一下有个清晰的[语法文档](https://pythonhosted.org/an_example_pypi_project/sphinx.html)，有意思的是也是用Sphinx 写的。
[官网](http://www.sphinx-doc.org/en/stable/rest.html)也有，但是感觉这个会比较好，可能是颜色的问题。
新建一个``

example.rst

 然后在

index.rst``

里按如下添加

title

title 的书写有几种和Html 中H标签对应 ``` H1 -- Top of Page Header

There should only be one of these per page and this will also -- when converting to pdf -- be used for the chapters.

H2 -- Page Sections

H3 -- Subsection

H4 -- Subsubsection +++++++++++++++++++ ```

table

我觉得优势就在Talbe 的写法上，Sphinx 支持三种table的格式

1. table (a table with title)
2. csv-table (a table generated from comma-separated values)
3. list-table (a table generated from a list of lists)

我觉得list-talbe 会比Markdown 的书写方式好，Markdown 的写法，很难让那些竖线对齐，当文字很长没有规则的时候写的时候就会很乱 list-talbe 没有这个问题，官网给出的一个例子

``` .. list-table:: Frozen Delights! :widths: 15 10 30 :header-rows: 1

• • Treat
  • Quantity
  • Description
• • Albatross
  • 2.99
  • On a stick!
• • Crunchy Frog
  • 1.49
  • If we took the bones out, it wouldn't be crunchy, now would it?
• • Gannet Ripple
  • 1.99
  • On a stick! ```

当然会有其他功能，可以添加图片之类的，链接......

部署

我是产生Html 静态文件然后用Nginx 代理这个目录。 在根目录下运行下面的命令，就可以在build 路径下产生html 文件，

make html

然后打开``

把Html和所有静态文件推到服务器上，配置Nginx 然后就可以访问了 Nginx 配置方法 见Nginx官网

如果你事件下来 发现得不到预期的结果，通常是你哪里有问题,比如书写的时候缩进没对齐，多了空格之类都会导致结果不正确。 Sphinx 还可以直接产生PDF文件。

也欢迎关注我的个人微信公众号：正午不早了

以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持 码农网

查看所有标签

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。