Sphinx补篇

https://blog.csdn.net/enjoyyl/article/details/97820201

http://www.latextemplates.com/svgnames-colors

https://woodenrobot.me/

https://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html

https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

https://docs.readthedocs.io/en/stable/webhooks.html

https://zh-sphinx-doc.readthedocs.io/en/latest/rest.html

我的写作习惯是用到的参考资料直接发出来,在阅读起来可能有一丝割裂感.但是在学习的感觉上是,由浅入深,由浅入深的感觉,以下的所有文章都是这样........

在说一下Sphinx是一种工具，可以将一组reStructuredText源文件转换为各种输出格式，自动生成交叉引用，索引等。也就是说，如果您的目录包含一堆reST格式的文档（可能还有文档的子目录）以及），Sphinx可以生成结构良好的HTML文件（在其他目录中），以方便浏览和导航。但是从同一来源，它还可以生成LaTeX文件，也可以将其编译为文档的PDF版本，或者直接使用rst2pdf编译为PDF文件。

当你用vscode打开一个rst文件时,会推荐这个插件,日本小哥写的

https://github.com/shuGH/vscode-table-formatter

.. yunswj documentation master file, created by
   sphinx-quickstart on Wed Dec  2 15:31:20 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to yunswj's documentation!
==================================

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



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

就是这个文件,事实上这个文件也可以是txt文件.但是我就写rst,咋啦

就像这样

在命令选项板（Ctrl-Shift-P或Cmd-Shift-P）中输入命令，并在表语法中使用光标位置。当前表格将被格式化。或者，您可以将所有表语法格式化为打开的文本。那时，标记语言是自动确定的。

命令标题：

• Table: Format Current
  • 格式化一个表语法仅包含当前光标位置
  • 命令： extension.table.formatCurrent
• Table: Format All
  • 将所有表格语法格式化为打开的文本
  • 命令： extension.table.formatAll

和文档说的一样

有自动补全就舒服

一个reStructuredText标记元素，它可以标记具有特殊含义的内容块。指令不仅由docutils提供，而且Sphinx和自定义扩展可以添加自己的指令。基本指令语法如下所示：

..指令名称::参数...
   ：option：值

   指令的内容。

要在LaTeX文档中使用这些颜色，只需\usepackage[svgnames]{xcolor}在你的序言中添加颜色，然后使用\color{}命令（例如\color{Navy}）选择一种颜色，之后所有文本将为你指定的颜色。

这个内容有点超纲,latex的渲染是学术界的共识,我之后会讲这个.假如我写论文的话.

https://sphinx-doc-zh.readthedocs.io/en/latest/config.html#build-config

基本配置

之前提及我们使用 conf.py 脚本来控制 Sphinx 怎么处理文档. 实际上这是个标准的 Python 脚本, 对于高级用户:可以嵌入自个儿的特殊任务,比如: 变更 sys.path, 或是导入另外的模块自动探察当前的文档版本.

相关配置项已经由 sphinx-quickstart 在初始化时写入 conf.py (使用 Py 的标准注释 # 将一些备选项,事先注释了) 要修订对应配置,只要先消除对应行的注释,并修订参数值就好. 想追加定制的参数,如果没由 sphinx-quickstart 预先生成,自个儿追加也就是了.

注意,要保持配置文件严格使用 Python 脚本语法,特别是 字串,数字,列表等等. 并且文件默认是以 UTF-0 编码保存的,已在首行进行聲明. 如果有参数值使用非ASCII 字串,就得使用Python 的 Unicode 聲明形式(project = u'Exposé')

源目录*在 :term:`资源目录` ,*编译目录 是我们指定的期望编译输出的目标目录. -b 选项可选择编译器; 当前实例Sphnix 将编译输出 HTML 文档.

其实 sphinx-quickstart 脚本已经创建了 Makefile 以及 make.bat 可以令我们更加简单的随时进行编译,只要

$ make html

这篇呢就是比较杂得一篇,属于上面文章得一个补篇.具体得这个文章还有一个语法,会讲reStructuredText以及MarkDown.会有一个简短得实例~