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/master/base_code/hello_diff.c
+++ /home/docs/checkouts/readthedocs.org/user_builds/pd-contribute-guide/checkouts/master/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;