当前位置:网站首页>Sphinx补篇

Sphinx补篇

2020-12-07 13:01:28 云深无际

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-PCmd-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.会有一个简短得实例~

本文分享自微信公众号 - 云深之无迹(TT1827652464) ,作者:云深之无迹

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间: 2020-12-02

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

版权声明
本文为[云深无际]所创,转载请带上原文链接,感谢
https://cloud.tencent.com/developer/article/1757172