3. 代码高亮¶
参考说明： http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive
支持的高亮语言： https://pygments.org/docs/lexers#lexers-for-various-shells
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¶
1#此命令在主机执行
2sudo apt install python
3echo "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¶
1#include <stdio.h>
2
3int main()
4{
5 printf("hello, world! This is a C program.\n");
6 for(int i=0;i<10;i++ ){
7 printf("output i=%d\n",i);
8 }
9
10 return 0;
11}
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¶
1module key_filter
2#(
3 parameter CNT_MAX = 20'd999_999 //计数器计数最大值
4)
5(
6 input wire sys_clk , //系统时钟50Mhz
7 input wire sys_rst_n , //全局复位
8 input wire key_in , //按键输入信号
9
10 output reg key_flag //key_flag为1时表示消抖后检测到按键被按下
11 //key_flag为0时表示没有检测到按键被按下
12);
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¶
1/* $begin hello */
2#include <stdio.h>
3
4int main()
5{
6 printf("hello, world! This is a C program.\n");
7 for(int i=0;i<10;i++ ){
8 printf("output i=%d\n",i);
9 }
10
11 return 0;
12}
13/* $end hello */
14
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¶
1echo "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¶
1#生成的可执行文件名
2
3hello:hello.o
4 gcc -o hello hello.o
5
6#生成规则
7hello.o:hello.c
8 gcc -c hello.c -o hello.o
9
10#伪目标
11.PHONY:clean
12clean:
13 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¶
1/* $begin hello */
2
3{
4 printf("hello, world! This is a C program.\n");
5 for(int i=0;i<10;i++ ){
6 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/pd-contribute-guide/checkouts/latest/base_code/hello_diff.c
+++ /home/docs/checkouts/readthedocs.org/user_builds/pd-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;