用sphinx-doc整理文档
程序员文章站
2022-03-15 17:33:56
...
最近有整理文档的需求,然后发现同事之前用的是sphinx-doc
,玩了一下,发现还是挺有趣的。这篇文章是做个小笔记,方便自己写
开始
# 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
便可替换。
语法格式
参考:
标题、列表、正文、要点
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分钟便可入手写文档,多好的工具啊 :)
玩~