欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

用sphinx-doc整理文档

程序员文章站 2022-03-15 17:33:56
...

最近有整理文档的需求,然后发现同事之前用的是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分钟便可入手写文档,多好的工具啊 :)

玩~

相关标签: 文档