代码高亮

3.7. 代码高亮#

参考说明： http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#toctree-directive

支持的高亮语言： https://pygments.org/docs/lexers#lexers-for-various-shells

3.7.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.7.2. code-block代码高亮#

shell 高亮测试#

高亮语法：

.. code-block:: sh
   :caption: test
   :name: test333
   :emphasize-lines: 2
   :linenos:

   #此命令在主机执行
   sudo apt install python
   echo "helloworld,this is a script test!"

效果：

代码 3.7.1 sh test#
1#此命令在主机执行
2sudo apt install python
3echo "helloworld,this is a script test!"

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;
   }

效果：

代码 3.7.2 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}

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时表示没有检测到按键被按下
   );

效果：

代码 3.7.3 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.7.3. literalinclude直接嵌入本地文件并高亮#

嵌入整个文件#

直接嵌入文件，包含标题、代码语言、高亮、带编号以及名称方便引用。

插入C代码#

.. literalinclude:: ./hello.c
   :caption: ./hello.c
   :language: c
   :emphasize-lines: 5,7-12
   :linenos:
   :name: hello.c

效果：

代码 3.7.4 ./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

插入shell代码#

语法：

.. literalinclude:: ./hello_world.sh
   :caption: ./hello_world.sh
   :language: sh
   :linenos:

效果：

代码 3.7.5 ./hello_world.sh#
1echo "helloworld,this is a script test!"

插入Makefile代码#

语法：

.. literalinclude:: ./Makefile
   :caption: ./Makefile
   :language: makefile
   :linenos:

效果：

代码 3.7.6 ./Makefile#
 1# Minimal makefile for Sphinx documentation
 2#
 3
 4# You can set these variables from the command line, and also
 5# from the environment for the first two.
 6SPHINXOPTS    ?=
 7SPHINXBUILD   ?= sphinx-build
 8SOURCEDIR     = .
 9BUILDDIR      = /tmp/_build_sphinx
10
11# Put it first so that "make" without argument is like "make help".
12help:
13	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14
15.PHONY: help Makefile
16
17# Catch-all target: route all unknown targets to Sphinx using the new
18# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
19%: Makefile
20	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

嵌入文件的某部分#

通过lines指定嵌入文件的某些行。

语法：

.. literalinclude:: ./hello.c
   :caption: ./hello.c
   :language: c
   :linenos:
   :lines: 1,3,5-8

效果：

代码 3.7.7 ./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);

文件对比#

语法：

.. literalinclude:: ./hello.c
:diff: ./hello_diff.c

效果：

--- /tmp/xx_bld_book_sphinx-note/hello_diff.c
+++ /tmp/xx_bld_book_sphinx-note/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;
目录