用sphinx-doc整理文档

版权声明：转载请邮件联系我([email protected])，以取得授权，谢谢！ https://blog.csdn.net/yeshennet/article/details/82595369

最近有整理文档的需求，然后发现同事之前用的是sphinx-doc，玩了一下，发现还是挺有趣的。这篇文章是做个小笔记，方便自己写

开始

官方：http://www.sphinx-doc.org/

# install:ubuntu 
apt-get install python-sphinx

# install :mac
brew install sphinx-doc

# create new project
sphinx-quickstart

编译与主题

sphinx 有一点简单的格式，和md格式类似，只需要加很少的标签，通过make html的指令，就能编译成很好看的html格式的文档。

make html

好看看起来是唯心的说法，我用的是 sphinx_rtd_theme

pip install sphinx_rtd_theme

不喜欢的话，修改下 conf.py 中的 html_theme 便可替换。

语法格式

参考：

os-sphinx-documentation

标题、列表、正文、要点

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.

Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.

Lists can be unnumbered like:

 * Item Foo
 * Item Bar

Or automatically numbered:

 #. Item 1
 #. Item 2

Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

表格

.. csv-table::
    :header:参数,类型,含义
    :widths:2,2,5

    test1,String,这里是测试的第一行
    test2,int,这里是测试的第二行

代码块

.. code-block:: xml

    public void test(){
        throws new Exception("this is a test");
    }

引用其他模块文件

.. toctree::
    :macdepth: 3

    module one
    module two

点击跳转

调用 :ref:`点击这里跳转<file.key>`

引用静态图片

.. image:: _static/system_activity.jpg

尾文

简单程度可比markdown，5分钟便可入手写文档，多好的工具啊 ：）

玩～