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
2
3
#此命令在主机执行
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
#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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
/* $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
1
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
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
#生成的可执行文件名

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
1
2
3
4
5
6
/* $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;