使用sphinx-doc优雅的书写html和项目介绍,包含restructureText常用语法

标签：sphinx doc make 列表 html 引用 脚注

​​跳转到我的gitee直接下载测试项目​​

​​​sphinx概述​​

​​使用nginx配置静态页面展示sphinx-doc 点击跳转​​

• 系统: win10 中WSL(Ubuntu18.04)
• 编辑器: VScode
• 插件:
  ​​​Sphinx 4.2.0​​



• 
  
• 快捷键: ​​ctr+j​​​ 弹出终端/ ​​ctr+b​​​弹出侧栏/ ​​ctrl+shift+r​​​弹出​​Preview index.rst​​页面

得到给点个赞哦

sphinx-doc:
Sphinx是一个工具，可以轻松创建

它最初是为​​Python​​文档创建的，它具有出色的工具，可用于各种语言的软件项目文档。

1. 输出格式: ​​HTML​​（包括​​Windows HTML​​帮助），​​LaTeX​​（适用于可打印的​​PDF​​版本），​​ePub​​，​​Texinfo​​，手册页，纯文本
2. 广泛的交叉引用: 语义标记和功能，类，引用，词汇表术语和类似信息的自动链接
3. 分层结构: 轻松定义文档树，自动链接到平级，上级和下级
4. 自动索引: 一般索引以及特定于语言的模块索引
5. 代码处理: 使用​​Pygments​​荧光笔自动突出显示
6. 扩展: 自动测试代码片段，包含​​Python模块​​（API文档）中的文档字符串等
7. 贡献的扩展: 用户在第二个存储库中贡献了50多个扩展;其中大多数可以从​​PyPI​​安装
8. ​​Sphinx​​使用​​reStructuredText​​作为其标记语言，其许多优点来自​​reStructuredText​​及其解析和翻译套件​​Docutils​​的强大功能和直接性。

文章目录

• 得到给点个赞哦
• 1. 安装和创建
• • 1.1. 创建一个根目录
  • 1.2. 安装和创建项目
• 2. 配置主题等
• • 2.1. 创建完成之后, conf.py里面保存的就是配置
  • 2.2. 设置html样式
• 3. restructureText语法
• • 3.1. 行内样式(斜体,粗体,等宽)
  • 3.2. 标题
  • 3.3. 段落
  • 3.4. 列表
  • • 3.4.1. 符号列表(Bullet Lists)
    • 3.4.2. 枚举(顺序)列表(Enumerated Lists)
    • 3.4.3. 定义列表(Definition Lists)
    • 3.4.4. 字段列表(Field Lists)
    • 3.4.5. 选项列表(Option Lists)
  • 3.5. 块,code-blocks
  • • 3.5.1. 文字块(Literal Blocks)
    • 3.5.2. 行块(Line Blocks)
    • 3.5.3. 块引用(Block Quotes)
    • 3.5.4. 文档测试块(Doctest Blocks)
  • 3.6. table
  • • 3.6.1. 网格表(Grid Tables)
    • 3.6.2. 简单表(Simple Tables)
  • 3.7. 分隔符
  • 3.8. 超链接
  • • 3.8.1. 自动超链接
    • 3.8.2. 外部超链接(External Hyperlink)
    • 3.8.3. 内部超链接|锚点(Internal Hyperlink)
    • 3.8.4. 匿名超链接(Anonymous hyperlink)
    • 3.8.5. 间接超链接(Indirect Hyperlink)
  • 3.9. 引用
  • • 3.9.1. 替换引用(Substitution Reference)
    • 3.9.2. 脚注引用(Footnote Reference)
    • 3.9.3. 引用参考(Citation Reference)
  • 3.10. 注释(Comments)
  • 3.9. 图片
• 4. 测试
• • 4.1. 添加两个页面
  • 4.2. 浏览器访问
• 5. Markdown文件直接显示
• 6. 检测到项目文件有修改,自动编译项目脚本
• 最后的部署到网络上
• • 方案一 nginx
  • 方案二 托管到readthedocs

1. 安装和创建

1.1. 创建一个根目录

创建一个文件夹作为根目录 sphinx_doc, 然后通过cd命令跳转到该文件夹里面, 在执行下面所有操作

1.2. 安装和创建项目

(base) :~$ pip install -U sphinx # 安装sphinx的Python包

(base) :sphinx_doc$ sphinx-quickstart # 创建一个sphinx项目
Welcome to the Sphinx 4.2.0 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

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 # 源路径与输出路径分开

The project name will occur in several places in the built documentation.
> Project name: find_work # 项目名称
> Author name(s): zjq # 作者名称
> Project release []: 0.1 # 版本号

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
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_CN # 中文, 语言列表看上面的网址

Creating file /mnt/c/Users/admin/OneDrive/sphinx_doc/source/conf.py.
Creating file /mnt/c/Users/admin/OneDrive/sphinx_doc/source/index.rst.
Creating file /mnt/c/Users/admin/OneDrive/sphinx_doc/Makefile.
Creating file /mnt/c/Users/admin/OneDrive/sphinx_doc/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /mnt/c/Users/admin/OneDrive/sphinx_doc/source/index.rst and create other 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.
# 源文件后缀名为 .rst(restructureText)
# 主页面index.rst, 编译后为index.html
(base) :sphinx_doc$

2. 配置主题等

2.1. 创建完成之后, conf.py里面保存的就是配置

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-LeWdfd3Z-1635908557146)(readme.assets/image-20211103091828055.png)]

2.2. 设置html样式

html_theme = 'alabaster'
# html_theme = 'sphinxdoc'
# html_theme = 'default'

3. restructureText语法

3.1. 行内样式(斜体,粗体,等宽)

1. 斜体

*重点(emphasis)通常显示为斜体*
`解释文字(interpreted text)通常显示为斜体`

2. 粗体

**重点强调(strong emphasis)通常显示为粗体**

3. 等宽

``行内文本(inline literal)通常显示为等宽文本，空格可以保留，但是换行不可以。``

3.2. 标题

=========
一级标题
=========
二级标题
=========

一级标题
^^^^^^^^
二级标题
---------
三级标题
>>>>>>>>>
四级标题
:::::::::
五级标题
'''''''''
六级标题
""""""""

当我们章节独立成文件rst, 章节标题是一级标题, ​​=​​号的个数要超过标题长度, 否则会报错, 其他标题如上所示, 使用方法跟一级标题一样

3.3. 段落

段落是被空行分割的文字片段，左侧必须对齐（没有空格，或者有相同多的空格）。
缩进的段落被视为引文。

3.4. 列表

3.4.1. 符号列表(Bullet Lists)

• 符号列表可以使用 -、 *、+ 来表示。
• 不同的符号结尾需要加上空行，下级列表需要有空格缩进。

- 符号列表1
- 符号列表2

  + 二级符号列表1

  - 二级符号列表2

  * 二级符号列表3

* 符号列表3

+ 符号列表4

3.4.2. 枚举(顺序)列表(Enumerated Lists)

• 枚举列表算即顺序(序号)列表，可以使用不同的枚举序号来表示列表。

1. 阿拉伯数字: 1, 2, 3, … (无上限)。
2. 大写字母: A-Z。
3. 小写字母: a-z。
4. 大写罗马数字: I, II, III, IV, …, MMMMCMXCIX (4999)。
5. 小写罗马数字: i, ii, iii, iv, …, mmmmcmxcix (4999)。

. 后缀: "1.", "A.", "a.", "I.", "i."。
() 包起来: "(1)", "(A)", "(a)", "(I)", "(i)"。
) 后缀: "1)", "A)", "a)", "I)", "i)"。

枚举列表可以结合 # 自动生成枚举序号。

1. 枚举列表1
#. 枚举列表2
#. 枚举列表3

(I) 枚举列表1
(#) 枚举列表2
(#) 枚举列表3

A) 枚举列表1
#) 枚举列表2
#) 枚举列表3

3.4.3. 定义列表(Definition Lists)

解释列表，即名词解释

• 条目占一行，解释文本要有缩进；多层可根据缩进实现。

定义1
 这是定义1的内容

定义2
 这是定义2的内容

3.4.4. 字段列表(Field Lists)

:标题: reStructuredText语法说明

:作者:
 - Seay
 - Seay1
 - Seay2

:时间: 2016年06月21日

:概述: 这是一篇
 关于reStructuredText

 语法说明。

3.4.5. 选项列表(Option Lists)

选项列表是一个类似两列的表格，左边是参数，右边是描述信息。当参数选项过长时，参数选项和描述信息各占一行。(选项与参数之间有一个空格，参数选项与描述信息之间至少有两个空格。)

-a            command-line option "a"
-b file       options can have arguments
              and long descriptions
--long        options can be long also
--input=file  long options can also have
              arguments
/V            DOS/VMS-style options too

3.5. 块,code-blocks

3.5.1. 文字块(Literal Blocks)

文字块就是一段文字信息，在需要插入文本块的段落后面加上​​::​​，接着一个空行，然后就是文字块了。

文字块不能定顶头写，要有缩进，结束标志是：新的一段文本贴开头，即没有缩进。

下面是文字块内容：
::

   这是一段文字块
   同样也是文字块
   还是文字块

这是新的一段。

3.5.2. 行块(Line Blocks)

行块对于地址、诗句以及无装饰列表是非常有用的。行块是以​​|​​开头，每一个行块可以是多段文本。

下面是行块内容(注意 | 和空格)：
 | 这是一段行块内容
 | 这同样也是行块内容
   还是行块内容

这是新的一段。

3.5.3. 块引用(Block Quotes)

块引用是通过缩进来实现的，引用块要在前面的段落基础上缩进。

通常引用结尾会加上出处(attribution)，出处的文字块开头是 --、— 、—，后面加上出处信息。

块引用可以使用空的注释 … 分隔上下的块引用。

注意在新的块和出处都要添加一个空行。

下面是引用的内容：

    “真的猛士，敢于直面惨淡的人生，敢于正视淋漓的鲜血。”

    --- 鲁迅

..

      “人生的意志和劳动将创造奇迹般的奇迹。”

      — 涅克拉索

3.5.4. 文档测试块(Doctest Blocks)

>>> print "This is a doctest block."
This is a doctest block.

3.6. 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)

3.6.1. 网格表(Grid Tables)

网格表中使用的符号有：-、=、|、+。

​​- 用来分隔行， = 用来分隔表头和表体行，| 用来分隔列，+ 用来表示行和列相交的节点。​​

Grid table:

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

3.6.2. 简单表(Simple Tables)

​​简单表相对于网格表，少了 | 和 + 两个符号，只用 - 和 = 表示。​​

Simple table:

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

3.7. 分隔符

分隔符就是一条水平的横线，是由 4 个 - 或者更多组成，需要添加换行。

上面部分

------------

下面部分

3.8. 超链接

3.8.1. 自动超链接

https://gitee.com/nwu_zjq/sphinx_doc

3.8.2. 外部超链接(External Hyperlink)

引用/参考(reference)，是简单的形式，只能是一个词语，引用的文字不能带有空格。

这篇文章来自我的Github,请参考 reference_。
# 注意这里有一个空行
.. _reference: https://gitee.com/nwu_zjq/sphinx_doc

这篇文章来自我的Github,请参考 `zjq的Github <https://gitee.com/nwu_zjq/sphinx_doc>`_。

3.8.3. 内部超链接|锚点(Internal Hyperlink)

更多信息参考 引用文档_

这里是其他内容

.. _引用文档: https://gitee.com/nwu_zjq/sphinx_doc

这是引用部分的内容

3.8.4. 匿名超链接(Anonymous hyperlink)

​​词组(短语)引用/参考(phrase reference)​​，引用的文字可以带有空格或者符号，需要使用反引号引起来。

这篇文章参考的是：`Quick reStructuredText`__。

.. __: http://docutils.sourceforge.net/docs/user/rst/quickref.html

3.8.5. 间接超链接(Indirect Hyperlink)

间接超链接是基于匿名链接的基础上的，就是将匿名链接地址换成了外部引用名​​_​​。

zjq_ 是 `我的 GitHub 用户名`__。

.. _zjq: https://gitee.com/nwu_zjq/sphinx_doc

__ zjq_

3.9. 引用

3.9.1. 替换引用(Substitution Reference)

替换引用就是用定义的指令替换对应的文字或图片，和内置指令(inline directives)类似。

这是 |logo| github的Logo，我的github用户名是:|name|。

.. |logo| image:: https://upload.jianshu.io/users/upload_avatars/1628444/6f0ea830-ad19-4153-874f-de9469437355.jpg?imageMogr2/auto-orient/strip|imageView2/1/w/80/h/80/format/webp
.. |name| replace:: zjq

3.9.2. 脚注引用(Footnote Reference)

脚注引用，有这几个方式：有手工序号(标记序号123之类)、自动序号(填入#号会自动填充序号)、自动符号(填入*会自动生成符号)。

手工序号可以和#结合使用，会自动延续手工的序号。

​​#​​表示的方法可以在后面加上一个名称，这个名称就会生成一个链接。

脚注引用一 [1]_
脚注引用二 [#]_
脚注引用三 [#链接]_
脚注引用四 [*]_
脚注引用五 [*]_
脚注引用六 [*]_

.. [1] 脚注内容一
.. [2] 脚注内容二
.. [#] 脚注内容三
.. [#链接] 脚注内容四 链接_
.. [*] 脚注内容五
.. [*] 脚注内容六
.. [*] 脚注内容七

3.9.3. 引用参考(Citation Reference)

引用参考与上面的脚注有点类似。

引用参考的内容通常放在页面结尾处，比如 [One]_，Two_

.. [One] 参考引用一
.. [Two] 参考引用二

3.10. 注释(Comments)

注释以 … 开头，后面接注释内容即可，可以是多行内容，多行时每行开头要加一个空格。

..
 我是注释内容
 你们看不到我

3.9. 图片

新建一个imsges目录 ，将图片放在此目录下 ，此目录与source目录属于同一级;

设置宽高一定要空三个空格 ，通过设置宽高来控制图片的尺寸

.. image:: ../images/1.jpg
   :width: 500
   :height: 500

4. 测试

4.1. 添加两个页面

make html # 生成html页面可以本地访问, 路径是 build/html
(base) :sphinx_doc$ make help
Sphinx v4.2.0
Please use `make target' where target is one of
  html        to make standalone HTML files
  dirhtml     to make HTML files named index.html in directories
  singlehtml  to make a single large HTML file
  pickle      to make pickle files
  json        to make JSON files
  htmlhelp    to make HTML files and an HTML help project
  qthelp      to make HTML files and a qthelp project
  devhelp     to make HTML files and a Devhelp project
  epub        to make an epub
  latex       to make LaTeX files, you can set PAPER=a4 or PAPER=letter
  latexpdf    to make LaTeX and PDF files (default pdflatex)
  latexpdfja  to make LaTeX files and run them through platex/dvipdfmx
  text        to make text files
  man         to make manual pages
  texinfo     to make Texinfo files
  info        to make Texinfo files and run them through makeinfo
  gettext     to make PO message catalogs
  changes     to make an overview of all changed/added/deprecated items
  xml         to make Docutils-native XML files
  pseudoxml   to make pseudoxml-XML files for display purposes
  linkcheck   to check all external links for integrity
  doctest     to run all doctests embedded in the documentation (if enabled)
  coverage    to run coverage check of the documentation (if enabled)
  clean       to remove everything in the build directory
(base) :sphinx_doc$

4.2. 浏览器访问

5. Markdown文件直接显示

由于​​Markdown​​其实才是我们常用的文本笔记记录格式, 因此想要把之前的​​Markdown​​直接加进来, 只需要两步即可
底层的原理很简单, 因为​​markdown​​也支持转化为​​html​​格式, 因此​​sphinx​​底层肯定支持这样干

• 安装Python包 ​​pip install recommonmark​​
• 修改​​conf.py​​文件中 ​​extensions = ['recommonmark']​​
• 跟​​rst​​文件一样调用



• 
  

6. 检测到项目文件有修改,自动编译项目脚本

检测到项目文件有修改, 自动编译项目脚本

最后的部署到网络上

方案一 nginx

使用nginx配置静态页面展示sphinx-doc 点击跳转

方案二 托管到readthedocs

前面使用Sphinx可以生成渲染的HTML页面，文档代码可以在Github中托管，但如果要外部访问和根据代码提交自动更新就需要有服务器了。购买VPS和搭建Nginx + Sphinx是比较原始可控的方案(方案一)，
更好的: RTFD(Read The Fuck Docs)就提供了非常好的文档托管服务。

首先在其官网 ​​Home | Read the Docs​​ 注册账号，建议关联​​Github​​账号，然后就可以​​Import Project​​也就是关联开源项目的文档文件和文档服务了。选择好​​Github项目的地址​​，还有填写文档服务名称，最终会生成 ​​https://$PROJECT_NAME.readthedocs.io​​ 地址供外部访问（可以与项目名不同，名字是先申请先得到，与pypi相同与github、gitbook不同）。

标签：sphinx,doc,make,列表,html,引用,脚注
From： https://blog.51cto.com/u_15888063/5882669