1. sphinx的安装与使用
1.1. 安装sphinx
sphinx官方安装说明： Installing Sphinx — Sphinx documentation
readthedoc官方说明： Getting Started with Sphinx — Read the Docs user documentation 7.0.0 documentation
总的来说步骤如下：
- 安装python3
- 通过python3安装sphinx包
- 根据项目要求安装项目的requirements.txt里的软件包
1.1.1. 安装python3
windows直接到python官网下载安装
Ubuntu下使用如下指令安装：
sudo apt install python3
1.1.2. 安装sphinx
windows下使用如下指令安装：
py -3 -m pip install sphinx #国内用户推荐使用清华源安装，使用-i指定源 py -3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx
Ubuntu下使用如下指令安装
python3 -m pip install sphinx #国内用户推荐使用清华源安装，使用-i指定源 python3 -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple sphinx #Ubuntu下可能还需要安装如下软件包 apt-get install python3-sphinx
1.2. 使用模板创建sphinx文档
本项目的sphinx已适配好支持markdown、默认的readthedoc主题等内容。
如果是要编写新的书籍，推荐直接使用本项目文档作为模版，修改conf.py文件的配置即可改变项目的名字、主题之类的内容。
1.2.1. 下载项目源码
先从github下载本项目源代码：
git clone git@github.com:Embdefire/ebf_contribute_guide.git
下载完成后，可看到本项目的结构大致如下：
├── README 说明文档或软链接至documentation中的说明，方便github阅读
├── base_code 配套代码
└── documentation 配套文档
├── faq 存储常见问题的文档
├── about_us.rst 关于我们
├── _build 文档编译输出目录
├── conf.py sphinx配置文件
├── contribute 如何参与项目，贡献与投稿的说明
├── foreword.rst 前言
├── index.rst 目录
├── make.bat
├── Makefile
├── media 文档中使用的图片文件
├── requirements.txt 文档的python依赖
├── _static
├── _templates
├── TODO.rst 待完成的内容，发布的任务列表
特别内容说明如下：
- base_code ：该目录通常存放项目的代码，
- documentation ：该目录通常存放项目的文档内容，如我们的rst、markdown文档。
1.2.2. 安装python依赖包
使用时，要先根据项目的 documentation/requirements.txt 安装依赖的python包。
#切换至requirements.txt文件的同级目录 cd documentation #requirements.txt文件的同级目录下执行后面的命令 #Windows指令，推荐使用powershell运行 py -3 -m pip install -r requirements.txt #Ubuntu指令 python3 -m pip install -r requirements.txt #国内用户推荐使用清华源安装 #Windows指令，推荐使用powershell运行 py -3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple #Ubuntu指令 python3 -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
1.2.3. 编写文档
安装好后，在项目的文档目录中添加rst或markdown文件即可， 建议使用vs code来编写文档，它非常方便预览文档， 可参考《 使用vscode编写rst文件》来搭建vscode预览sphinx文档的环境。
编写文档时的语法和规范可参考以下内容：
- 《 ReST基础语法》
- 《 野火sphinx文档规范》
- 《 Markdown示例》
1.3. 编译文档
如果使用了vscode的rst插件，可以直接保存rst文件后它会自动编译并可预览。
也可以手动编译，到文档源码所在的makefile目录，执行如下命令：
#在文档的makefile目录下执行 #Windows指令 make.bat html #Ubuntu指令 make html
在设定的build或_build的html目录下会生成静态的html文件。可直接使用这些静态的html文件制作网站。
1.4. 在本地预览文档
vscode插件预览有时不够完整，可以在本地开启一个python服务器来预览。 进入到生成的_build/html目录，运行如下指令：
#在生成的html目录执行如下指令 #Windows py -3 -m http.server 8000 #Ubuntu python3 -m http.server 8000
运行指令后，在浏览器中打开 http://localhost:8000 即可查看生成的静态网页。
1.5. 允许其它主机预览文档
类似地，若要允许其它主机访问自己的文档，执行如下命令即可
#在生成的html目录执行如下指令 #Windows py -3 -m http.server --bind 0.0.0.0 8000 #Ubuntu python3 -m http.server --bind 0.0.0.0 8000
运行指令后，在浏览器中打开 http://主机IP:8000 即可查看生成的静态网页。
1.6. 清除编译输出
有时html文件不会完全达到我们修改rst后的效果，这可能是因为之前的旧文件影响， 这时可以先清除编译输出再重新编译。
#清除编译输出 #Windows指令 make.bat clean #Ubuntu指令 make clean #重新编译 #Windows指令 make.bat html #Ubuntu指令 make html
1.7. 创建全新的sphinx文档
若不想使用本工程模版，可以使用如下指令创建全新的文档。
sphinx-quickstart
按照提示回答问题即可。 推荐使用默认的_build目录，与vscode保持一致。 其中提示语言时可以使用这个中文代码：zh_CN
sphinx默认不支持markdown语法，要支持的话请参考本模版的conf.py文件配置。
2. 使用vscode编写rst文件
使用vscode编写sphinx文档非常方便，可以即时预览和自动编译。
rst vscode插件说明页：reStructuredText Extension for Visual Studio Code — restructuredtext 1.0 documentation
另外，vscode默认支持markdown单个文件的预览。
2.1. reStructuredText插件
需要安装的vscode插件：
- python
- reStructuredText
安装python插件后，要选择使用python3的解释器，不要使用python2。
安装reStructuredText插件后，打开rst文件，点击预览按钮。
会提示使用sphinx还是doctuil工具，我们选择使用sphinx。
若配置正确，稍等一会即可在右侧看到预览效果。
2.2. Table Formater插件
使用Table Formater可以方便格式化表格，支持markdown和rst Table Formatter - Visual Studio Marketplace
插件名：Table Formatter
安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All
3. docx批量转rst方法
3.1. 按章分割word文档
1.将所需转换的文档放入一个新的文件夹中
2.打开文档，进入大纲视图
3.合理选择显示级别，取消显示文本格式的选项后将显示本文档所有的章节名
4.点击第n章前的加号按钮，选中本章，点击显示文档按钮，出现创建选项
5.点击创建按钮之后如图所示
6.所有章都按上述方法操作，点击保存
7.文件夹中就出现了分割好的单独docx格式的文件，删除原来整本的文档
3.2. 批量将分割后的docx转换为rst
1.将分割后的文件改成对应的英文名以方便转换
2.新建一个文本文档，内容如下，获取当前列表中的文件名
DIR *.* /B >LIST.TXT
3.将新建文本文档的后缀名改为 .bat后双击运行得到 了LIST.TXT ，
4.用notepad++打开LIST.TXT,删除图中的两行
5.鼠标：alt+鼠标左键选择中所有的行。键盘：alt+shift+方向鍵将位置调整到行首。输入rstfromdocx -lurg 后保存。
rstfromdocx -lurg
6.在文档所在的文件夹按住shift键和点击鼠标右键，选中打开powershell，
7.全选上面编辑好的文档列表然后复制到powershell中，鼠标右键复制，文档开始转换
8.完成后就得到了转换好的文件，将转换好的文件复制到一个新文件夹中，防止接下来的操作失败，注意备份
3.3. 批量将.rest修改为.rst并删除不需要的文件
1.在新文件夹中新建一个.bat文件，并复制以下内容保存后运行
del *.py /s
del index.rest /s
del Makefile /s
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.rest"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.png"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.jpeg"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.jpg"') do (move "%%i" "%%~dpi./../")
for /f "tokens=* delims=" %%i in ('dir /b /a-d /s "*.bmp"') do (move "%%i" "%%~dpi./../")
echo.
echo 正在删除当前目录及子目录中所有的空文件夹，请稍后......
echo -------------------------------------------------------------
cd. > listnull.txt
for /f "delims=" %%i in ('dir /ad /b /s') do (
dir /b "%%i" | findstr .>nul || echo %%i >> listnull.txt
)
set /a sum=0
for /f "tokens=*" %%i in (listnull.txt) do (
rd /q "%%i"
echo 成功删除空目录：%%i
set /a sum=sum+1
)
echo -------------------------------------------------------------
echo 共成功删除%cd%目录及其子目录下%sum%个空文件夹！
echo.
set sum=
ren *.rest *.rst
del listnull.txt
exit
上述代码的作用是删除不需要的文件和空文件夹，并将图片文件移动到上一级目录下，然后将rest更名为rst
2.新建一个media文件夹，并将存放图片的文件夹移动至media文件夹，至此，批量转换完成
1. ReST基础语法
rst的基础语法和markdown差不多，
可以使用这个在线的rst编辑器了解相关语法：rst在线编辑器
- sphinx语法官网：reStructuredText Primer — Sphinx documentation
- restruct语法官网：reStructuredText
下面是常用语法：
语法：
一级标题 ============================== 二级标题 ~~~~~~~~~~~~~~~ 三级标题 ------------------ 四级标题 ^^^^^^^^^^^^^^^^^^^^^ 五级标题 """"""""""""""""" 六级标题 ***************** **强调** *斜体* ``monospace,会变色，具体作用不清楚`` 无序列表 --------------------------- - hhhhhhhh - hhhhhhhh - hhhhhhhh - hhhhhhhh - hhhhhhhh - hhhhhhhh 有序列表 ------------------------ 支持数字、大小写字母和罗马数字 1. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh a. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh #. hhhhhhhh
效果：
强调
斜体
monospace,会变色，具体作用不清楚
1.1. 无序列表
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
1.2. 有序列表
支持数字、大小写字母和罗马数字
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
- hhhhhhhh
1.3. 表格
表格语法说明：reStructuredText Directives
推荐使用列表式表格，修改比较方便
1.3.1. 列表式表格
语法：
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
效果：
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
1.3.2. 普通表格
表格使用 == 号制作
语法示例：
===== ===== ======= A B A and B ===== ===== ======= False False False True False False False True False True True True ===== ===== =======
效果：
| A | B | A and B |
|---|---|---|
| False | False | False |
| True | False | False |
| False | True | False |
| True | True | True |
在vscode可安装插件方便格式化表格：Table Formatter - Visual Studio Marketplace
安装后通过Ctrl-Shift-P调用 Table: Format Current 或 Table: Format All
1.3.3. CSV表格
使用CSV编写
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
效果：
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
2. 超链接与文件引用
参考说明：Roles — Sphinx documentation
2.1. 超链接
语法：
直接嵌入网址： `野火公司官网 <http://www.embedfire.com>`_ 使用引用的方式把具体网址定义在其它地方： `野火公司官网`_ .. _野火公司官网: http://www.embedfire.com
效果：
直接嵌入网址：
使用引用的方式把具体网址定义在其它地方： 野火公司官网
2.2. 引用
2.2.1. 引用图片、表格
在图片、表格上面加一个引用标签，然后通过 ref指令引用。 语法：
.. _my-reference-label支持中文: .. figure: ../media/rest-syntax/pic-video/logo.png :alt: 野火logo :align: center 引用方式 :ref:`my-reference-label支持中文` 。
效果：
必须写这个图片名
引用方式 必须写这个图片名 。
表格引用：
.. _拨码开关启动配置表: .. table:: 拨码开关启动配置表 ==== ====== ========== ==== == === 编号 名称 NAND FLASH eMMC SD USB ==== ====== ========== ==== == === 1 MODE0 0 0 0 1 2 MODE1 1 1 1 0 3 CFG1-4 1 0 0 X 4 CFG1-5 0 1 0 X 5 CFG1-6 0 1 1 X 6 CFG1-7 1 0 0 X 7 CFG2-3 0 1 0 X 8 CFG2-5 0 0 1 X ==== ====== ========== ==== == === 引用示例 :ref:`拨码开关启动配置表` 。 自定义名称引用 :ref:`自定义名称 <拨码开关启动配置表>` 。
效果：
| 编号 | 名称 | NAND FLASH | eMMC | SD | USB |
|---|---|---|---|---|---|
| 1 | MODE0 | 0 | 0 | 0 | 1 |
| 2 | MODE1 | 1 | 1 | 1 | 0 |
| 3 | CFG1-4 | 1 | 0 | 0 | X |
| 4 | CFG1-5 | 0 | 1 | 0 | X |
| 5 | CFG1-6 | 0 | 1 | 1 | X |
| 6 | CFG1-7 | 1 | 0 | 0 | X |
| 7 | CFG2-3 | 0 | 1 | 0 | X |
| 8 | CFG2-5 | 0 | 0 | 1 | X |
引用示例 拨码开关启动配置表 。 自定义名称引用 自定义名称 。
2.2.2. 引用文档
语法：
自定义引用文字 :doc:`引用本地的其它rst文档,rst后缀要省略，如about_us <../about_us>` 使用标题文字 :doc:`../about_us`
效果：
自定义引用文字
引用本地的其它rst文档,rst后缀要省略，如about_us
使用标题文字 关于野火
2.2.3. 使用标签引用文档
要在被引用的文件头定义标签，如about_us.rst文件头写 “about_embedfire” 的标签，具体请查看该文档的源码
语法：
:ref:`自定义链接文字 <about_embedfire>` :ref:`about_embedfire`
效果：
若要跨文档引用标题，可以使用自动切片扩展插件，它的使用方式如下：
某个文档：
============= Some Document ============= Internal Headline =================
然后在另一个文档引用：
=============== Some Other Doc =============== A link- :ref:`Internal Headline`
此扩展程序是内置的，因此您只需编辑即可 conf.py
extensions = [
.
. other
. extensions
. already
. listed
.
'sphinx.ext.autosectionlabel',
]
您唯一需要注意的是，现在您无法在整个文档集合中复制内部标题。
2.2.4. 引用非rst文档
会呈现出点击后下载文件的效果。注意这种引用方式在生成pdf文件时链接会无效。
语法：
:download:`引用非rst的本地文档 <../requirements.txt>`.
效果：
3. 代码高亮
参考说明： Directives — Sphinx documentation
支持的高亮语言： Available lexers — Pygments
3.1. 快速定义代码块
使用简便的预定义高亮语法高亮缩进，默认不带语言说明的都使用highlight定义的语言高亮， 然后可以直接使用“::”两个冒号代替“code-block”指令快速定义其它代码块， 直到下一个highlight指令，才会改变语言：
.. highlight:: sh 此指令后如下的“::”定义的块都会以sh语法进行高亮，直到遇到下一条highlight指令。 :: #此命令在主机执行 sudo apt install python echo "helloworld,this is a script test!"
效果：
#此命令在主机执行 sudo apt install python echo "helloworld,this is a script test!"
3.2. code-block代码高亮
3.2.1. shell 高亮测试
高亮语法：
.. code-block:: sh :caption: test :name: test333 :emphasize-lines: 2 :linenos: #此命令在主机执行 sudo apt install python echo "helloworld,this is a script test!"
效果：
sh test
#此命令在主机执行 sudo apt install python echo "helloworld,this is a script test!" |
3.2.2. C高亮测试
语法：
.. code-block:: c
:caption: c test
:emphasize-lines: 4,5
:linenos:
#include <stdio.h>
int main()
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
printf("output i=%d\n",i);
}
return 0;
}
效果：
c test
#include <stdio.h>
int main()
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
printf("output i=%d\n",i);
}
return 0;
}
|
3.2.3. verilog高亮测试
语法：
使用verilog或v进行高亮
.. code-block:: v
:caption: verilog test
:emphasize-lines: 4,5
:linenos:
module key_filter
#(
parameter CNT_MAX = 20'd999_999 //计数器计数最大值
)
(
input wire sys_clk , //系统时钟50Mhz
input wire sys_rst_n , //全局复位
input wire key_in , //按键输入信号
output reg key_flag //key_flag为1时表示消抖后检测到按键被按下
//key_flag为0时表示没有检测到按键被按下
);
效果：
verilog test
module key_filter
#(
parameter CNT_MAX = 20'd999_999 //计数器计数最大值
)
(
input wire sys_clk , //系统时钟50Mhz
input wire sys_rst_n , //全局复位
input wire key_in , //按键输入信号
output reg key_flag //key_flag为1时表示消抖后检测到按键被按下
//key_flag为0时表示没有检测到按键被按下
);
|
3.3. literalinclude直接嵌入本地文件并高亮
3.3.1. 嵌入整个文件
直接嵌入文件，包含标题、代码语言、高亮、带编号以及名称方便引用。
3.3.1.1. 插入C代码
.. literalinclude:: ../../base_code/hello.c :caption: ../../base_code/hello.c :language: c :emphasize-lines: 5,7-12 :linenos: :name: hello.c
效果：
../../base_code/hello.c
/* $begin hello */
#include <stdio.h>
int main()
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
printf("output i=%d\n",i);
}
return 0;
}
/* $end hello */
|
3.3.1.2. 插入shell代码
语法：
.. literalinclude:: ../../base_code/hello_world.sh :caption: ../../base_code/hello_world.sh :language: sh :linenos:
效果：
../../base_code/hello_world.sh
echo "helloworld,this is a script test!" |
3.3.1.3. 插入Makefile代码
语法：
.. literalinclude:: ../../base_code/Makefile :caption: ../../base_code/Makefile :language: makefile :linenos:
效果：
../../base_code/Makefile
#生成的可执行文件名 hello:hello.o gcc -o hello hello.o #生成规则 hello.o:hello.c gcc -c hello.c -o hello.o #伪目标 .PHONY:clean clean: rm -f *.o hello |
3.3.2. 嵌入文件的某部分
通过lines指定嵌入文件的某些行。
语法：
.. literalinclude:: ../../base_code/hello.c :caption: ../../base_code/hello.c :language: c :linenos: :lines: 1,3,5-8
效果：
../../base_code/hello.c
/* $begin hello */
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
printf("output i=%d\n",i);
|
3.3.3. 文件对比
语法：
.. literalinclude:: ../../base_code/hello.c :diff: ../../base_code/hello_diff.c
效果：
--- /home/docs/checkouts/readthedocs.org/user_builds/ebf-contribute-guide/checkouts/latest/base_code/hello_diff.c
+++ /home/docs/checkouts/readthedocs.org/user_builds/ebf-contribute-guide/checkouts/latest/base_code/hello.c
@@ -5,7 +5,7 @@
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
- printf("diff output i=%d\n",i);
+ printf("output i=%d\n",i);
}
return 0;
4. 图片与视频
添加图片的sphinx说明：reStructuredText Primer — Sphinx documentation 添加图片的rst官方说明：
4.1. 图片
图片原文件统一存储在引用文档所在的同级目录的 media 文件夹下。
显示图片直接使用image或figure指令，无特殊情况的话我们书籍图片要求使用居中方式显示， 还需要添加“alt”选项指定图片的描述（类似doc中的题注），以便图片加载失败时显示文字
不要使用bmp图片 ，bmp图片在生成pdf的时候会丢失，所以不要使用bmp格式的图片。
4.1.1. figure命令
语法：
.. figure: ../media/rest-syntax/pic-video/logo.png :alt: 野火logo :align: center :caption: 野火logo
效果：
4.1.2. image命令：
语法：
.. image:: ../media/rest-syntax/pic-video/logo.png :align: center :alt: 野火logo
效果：
以下的图片显示方式是word自动转换的结果，使用这种方式无法以居中形式显示图片，所以我们要修改。
它的原理是使用“||”类似宏的方式替换指令，使rst源码看起来更简洁，但不能居中显示。
语法：
|logo|,使用"|宏名|"的形式替换文字。 .. |logo| image:: ../media/rest-syntax/pic-video/logo.png
效果：
,使用”|”宏名”|”的形式替换文字。
图片还可以使用 width、heigh、scale等参数，但不推荐使用，设置过width、height参数的图片， 在页面可以点击查看原图。
语法：
.. image:: ../media/rest-syntax/pic-video/logo.png :align: center :width: 5.63529in :height: 0.97222in
效果：
4.2. 视频
使用raw指令插入html代码。 直接粘贴视频网站的通用html代码，不过貌似不能放大。
在vscode可能无法预览，直接在浏览器中看即可。
注解
TODO：目前还不知道如何放大，以及点击后到具体的视频网站播放。
语法：
.. raw:: html <iframe src="//player.bilibili.com/player.html?aid=70961112&cid=122951107&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>
效果：
语法：
.. raw:: html <iframe height=498 width=510 src='http://player.youku.com/embed/XMzk2MzQxNTQ3Ng==' frameborder=0 'allowfullscreen'></iframe>
5. 数学符号和公式
数学符号和公式
5.1. 上标
使用sub表示平方等符号：
语法
I\ :sup:`2`\ C
效果：
I2C
6. 特殊提示
特殊提示支持警告、重要、提示、注意等标签，适合做显眼的用途。
- attention
- caution
- danger
- error
- hint
- important
- note
- tip
- warning
语法：
.. note:: This is a note admonition. This is the second line of the first paragraph. - The note contains all indented body elements following. - It includes this bullet list. .. hint:: This is a hint admonition. .. important:: This is a important admonition. .. tip:: This is a tip admonition. .. warning:: This is a warning admonition. .. caution:: This is a caution admonition. .. attention:: This is a attention admonition. .. error:: This is a error admonition. .. danger:: This is a danger admonition.
效果：
注解
This is a note admonition. This is the second line of the first paragraph.
- The note contains all indented body elements following.
- It includes this bullet list.
提示
This is a hint admonition.
重要
This is a important admonition.
小技巧
This is a tip admonition.
警告
This is a warning admonition.
警告
This is a caution admonition.
注意
This is a attention admonition.
错误
This is a error admonition.
危险
This is a danger admonition.
7. rst的指令和角色（directive and role）
- directive说明：reStructuredText Directives
- role说明：reStructuredText Interpreted Text Roles
rst使用directive和role进行特殊操作。
7.1. directive
directive的格式为：
.. directive名:: 参数 :参数: :参数:
7.2. role
role的格式为：
:role名: 内容
8. 野火sphinx文档规范
开源项目的整体目录：
├── README 说明文档或软链接至documentation中的说明，方便github阅读
├── base_code 配套代码
└── documentation 配套文档
├── faq 存储常见问题的文档
├── about_us.rst 关于我们
├── _build 文档编译输出目录
├── conf.py sphinx配置文件
├── contribute 如何参与项目，贡献与投稿的说明
├── foreword.rst 前言
├── index.rst 目录
├── make.bat
├── Makefile
├── media 文档中使用的图片文件
├── requirements.txt 文档的python依赖
├── _static
├── _templates
├── TODO.rst 待完成的内容，发布的任务列表
注意：每次新添加了rst文档，必须要修改documentation文件夹下的index.rst文件，将新增的rst文件，添加到对应的地方。
8.1. 图片
文档引用的图片存储在文档源码目录下的media文件夹中，按部分、章节及文档分目录存储。
图片要直接使用如下形式,方便居中：
.. image:: media/logo.png :align: center
不要使用如下形式，如下形式是docx转换后的格式，它不支持居中，见到要把它改好。
|logo| .. |logo| image:: media/logo.png
8.2. rst格式检查
使用vscode的rst插件在编写时就会有格式检查。编写文档时应尽量满足该格式检查的规范。 对于docx转rst后的不规范文档，做到见一个改一个。
make html时，编译会有提示输出，尽量让它不输出的warning。
8.3. 文档编码和回车
文档编码统一用“utf-8”， 回车使用“LF”，不要使用“CRLF”，文档编码和回车可在VS-Code的右下角设置。
8.4. 代码引用
超过3行的代码要加上行号、并用caption名指明代码片段的名，对于引用的代码文件，使用caption指明引用的路径名。
如以下语法：
.. literalinclude:: ../../base_code/hello.c :caption: ../../base_code/hello.c :language: c :linenos:
8.5. 类似docx的题注引用
rst可通过链接实现类似doc的题注引用，它通过给内容添加 :name: 属性来实现， 代码、图片、表格等都可以使用这种方式，使用 :name: 属性来定义引用名，通过引用名+下划线来实现引用：
语法：
.. literalinclude:: ../../base_code/hello.c :caption: ../../base_code/hello.c :language: c :name: 代码清单或自己起的引用名字 :linenos: 引用的方式是使用 ":name:"定义的名字加下划线 "_",如： 代码清单或自己起的引用名字_
效果：
../../base_code/hello.c
/* $begin hello */
#include <stdio.h>
int main()
{
printf("hello, world! This is a C program.\n");
for(int i=0;i<10;i++ ){
printf("output i=%d\n",i);
}
return 0;
}
/* $end hello */
|
引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：
语法：
.. image:: ../media/rest-syntax/pic-video/logo.png :align: center :name: 野火logo 引用的方式是使用 ":name:"定义的名字加下划线 "_",如： 野火logo_
效果：
引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：
语法：
.. list-table:: Frozen Delights!
:widths: 15 10 30
:header-rows: 1
:name: 测试表格
* - Treat
- Quantity
- Description
* - Albatross
- 2.99
- On a stick!
* - Crunchy Frog
- 1.49
- If we took the bones out, it wouldn't be
crunchy, now would it?
* - Gannet Ripple
- 1.99
- On a stick!
引用的方式是使用 ":name:"定义的名字加下划线 "_",如：
测试表格_
效果：
| Treat | Quantity | Description |
|---|---|---|
| Albatross | 2.99 | On a stick! |
| Crunchy Frog | 1.49 | If we took the bones out, it wouldn’t be crunchy, now would it? |
| Gannet Ripple | 1.99 | On a stick! |
引用的方式是使用 “:name:”定义的名字加下划线 “_”,如：
换皮肤
This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devices. This theme is used primarily on Read the Docs but can work with any Sphinx project. You can find a working demo of the theme in the theme documentation
Installation
This theme is distributed on PyPI and can be installed with pip:
$ pip install sphinx-rtd-theme
To use the theme in your Sphinx project, you will need to edit your conf.py file’s html_theme setting:
html_theme = "sphinx_rtd_theme"
2706
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
