sphinx常用语法

先决条件

  • Windows 10
  • Python 3.6 or Anaconda

安装sphinx

pip install -U sphinx
#根据提示可能需要先升级pip
python -m pip install --upgrade pip

如果使用Anaconda

conda install sphinx

初始化

#先到一个目录下
cd /d d:
sphinx-quickstart Linux
#会自动创建Linux文件夹

#开始回答问题,全部按Y,没有Y的地方,是默认回车
#所有的设置都可以在source/conf.py里面修改

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y
#是否分离源目录和编译目录

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:
#模板和静态文件文件夹是否使用下横杠作为前缀

The project name will occur in several places in the built documentation.
> Project name: Linux #项目名称
> Author name(s): hai #作者名称
> Project release []: www.cybperpioneer.net/docs #发布地址

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
http://sphinx-doc.org/config.html#confval-language.
> Project language [en]: zh_CN
#项目语言

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:
#内容文件使用.rst后缀

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:
#是否使用index作为主页

#下面是否开启插件
Indicate which of the following Sphinx extensions should be enabled:
> autodoc: automatically insert docstrings from modules (y/n) [n]:y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]
: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: y

> viewcode: include links to the source code of documented Python objects (y/n)
[n]: y
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/
n) [n]: y
Note: imgmath and mathjax cannot be enabled at the same time. imgmath has been d
eselected.

A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (y/n) [y]:
#是否创建编译文件

> Create Windows command file? (y/n) [y]: 
#是否创建Windows命令行文件(批处理)

Creating file opensuse\source\conf.py.
Creating file opensuse\source\index.rst.
Creating file opensuse\Makefile.
Creating file opensuse\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file opensuse\source\index.rst and create ot
her documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

使用

在source下面创建文档的目录结构与文件
示例
可以手动创建也可以使用cmd创建

mkdir chapter1 && cd chapter1 && cd . > section1.rst && cd ..
mkdir chapter2 && cd chapter2 && cd . > section1.rst && cd ..
mkdir chapter3 && cd chapter3 && cd . > section1.rst && cd ..

此时的目录结构

C:\Users\test1\Downloads\opensuse\source>tree /F
文件夹 PATH 列表
卷序列号为 E0E1-B031
C:.
│  conf.py
│  index.rst
│
├─chapter1
│      section1.rst
│
├─chapter2
│      section1.rst
│
├─chapter3
│      section1.rst
│
├─_static
└─_templates

编辑

编辑source目录下的index.rst文件,推荐使用notepad++,对于良好的中文支持是utf-8编码;在下面添加刚刚内容索引,注意tab缩进

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


   chapter1/section1.rst
   chapter2/section1.rst
   chapter3/section1.rst

toctree:目录树
maxdepth 2:最大目录深度
caption: Contents:标题等于内容标题
numbered:标题编号

安装新主题

pip install sphinx_rtd_theme

修改source/conf.py

html_theme = 'sphinx_rtd_theme'

生成文件

到项目目录下执行make html
做完项目并且生成之后,就可以拷贝走Linux目录下的HTML目录,放在任何地方

语法

最终效果和使用的主题有关系

标题

1. 一级标题
============

1.1 二级标题
-------------

1.1.1 三级标题
+++++++++++++++

符号长度一定要超过标题的长度,否则生成HTML的时候会报错
子标题也可以使用缩进

列表

- 无序列表
- 无序列表
- 无序列表

1. 有序列表
2. 有序列表
3. 有序列表

超链接

这是 `我的博客`_

.. _我的博客: https:://www.cyberpioneer.net/

#或者

`我的博客 <https://www.cyberpioneer.net/>`_

*斜体*

**加粗**

语内的标记 ``标记1``
语内的标记 `标记2`
#注意有空格,否则不显示

图片

本地引用image

.. image:: image/pic.jpg
    :height: 300
    :width: 300
    :scale: 50
    :alt: 风景如画
    :align: center

.. 或者

.. image:: image/pic.jpg
    :name: my picture

本地引用figure

.. figure:: image/pic.jpg
    :scale 20 %
    :alt 风景如画

    泰勒斯威夫特不但漂亮

    而且嗓音也好听

#两种的区别是figure可以对图片增加描述

外链图片

这是一张 `图片 <http://www.laughspark.info/uploadfiles/taylor-swift-look-cute-635798553212805494-17329.jpg>`_

#注意空格

### 注释

任何以..开头,但不使用任何指令的文本,都被解释为注释

.. 这是一个注释

.. 
    这也是一个注释

特殊段落标记

.. note::
    这是一个注解

.. warning::
    这是一个警告

.. tip::
    这是一个提示

.. todo::
    这是一个待办

.. attention::
    这是一个注意

.. caution::
    这是一个警告

.. danger::
    这是一个危险

.. error::
    这是一个错误

.. hint::
    这是一个暗示

.. important::
    这是一个重要

rubric
类似于title,但生产的标题与章节无关,不会成为文章结构的一部分

字体颜色

.. role:: red

    部分字体是 :red:`红色`
.. container:: red
    我这一行都是红色

我是第二行

.. class:: red

都是红色

.. admonition:: big warning
    :class: red
    我是红色行

代码块

.. code-block:: bash
    :linenos:
    :emphasize-lines: 3,4

    sudo systemctl start apache2
    sudo systemctl restart nginx
    sudo firewall-cmd --add-service=http --permanent
    sudo firewall-cmd --reload

#:linenos:增加行号
#:emphasize-lines: 3,4强调3,4行

#或者

.. code::

    sudo rm -rf /

行内命令

千万不要在生产环境执行 `rm -rf /` 这个命令
#注意符号前后有空格

表格

同样的,符号要能包裹内容长度

== ==
aA bB
cC dD
== ==

#或者

.. list-table:: table title

    * - 第一行第一列
      - 第一行第二列
      - 第一行第三列
    * - 第二行第一列
      - 第二行第二列
      - 第二行第三列
    * - 第三行第一列
      - 第三行第二列
      - 第三行第三列

#以此类推,表格内容支持行内标记语法

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

跨列的

=====  =====  ======
Inputs        Output
------------  ------
  A      B    A or B
=====  =====  ======
False         False
------------  ------
True   False  True
False  True   True
True          True
============  ======

使用换行符的

===========  ================
1. Hallo     | blah blah blah
               blah blah blah
               blah
             | blah blah
2. Here      We can wrap the
             text in source
32. There    **aha**
===========  ================

格子表

+--------+--------+-----------+
| Header | Header with 2 cols |
+========+========+===========+
| A      | Lists: | **C**     |
+--------+  - aha +-----------+
| B::    |  - yes | | a block |
|        |        |   of text |
|  *hey* |  #. hi | | a break |
+--------+--------+-----------+

csv表

.. csv-table:: Balance Sheet
   :header: Description,In,Out,Balance
   :widths: 20, 10, 10, 10
   :stub-columns: 1

   Travel,,230.00,-230.00
   Fees,,400.00,-630.00
   Grant,700.00,,70.00
   Train Fare,,70.00,**0.00**

列表

.. list-table:: Weather forecast
   :header-rows: 1
   :widths: 7 7 7 7 60
   :stub-columns: 1

   *  -  Day
      -  Min Temp
      -  Max Temp
      -
      -  Summary
   *  -  Monday
      -  11C
      -  22C
      -  .. image:: _static/sunny.svg
            :width: 30
      -  A clear day with lots of sunshine.
         However, the strong breeze will bring
         down the temperatures.
   *  -  Tuesday
      -  9C
      -  10C

脚注

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

#还可以显式编号脚注([1]_)或使用不带名称([#]_)的自动编号脚注。

基本上常用的就这类,但还有很多,sphinx语法相当复杂且格式要求极其严格,有一个缩进不对要么没有效果,要么报错

参考链接

  • https://rest-sphinx-memo.readthedocs.io/en/latest/index.html
  • http://notes.tanchuanqi.com/tools/reStructuredText.html

You may also like...

发表评论

电子邮件地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据