> For the complete documentation index, see [llms.txt](https://huataihuang.gitbook.io/cloud-atlas-draft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://huataihuang.gitbook.io/cloud-atlas-draft/develop/doc/sphinx/sphinx_embed_code.md).

# sphinx文档的代码展示

在Sphinx文档中可以嵌入源代码文件，也可以选择嵌入片段，语法高亮采用 [Pygments](http://pygments.org/) 处理，支持大量语法。

## 语法高亮

* 语法高亮采用 `.. highlight:: language` :

```
.. highlight:: c
```

* 并且支持代码块:

```
.. code-block:: ruby

   Some Ruby code.
```

## 代码行号

* `code-block` 的参数 `:linenos:` 提供了行号 

```
.. code-block:: ruby
   :linenos:

   Some more Ruby code.
```

* 代码指定行高亮

```
.. code-block:: python
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'
```

## 包含

我感觉非常方便的是使用 `.. literalinclude:: filename` ，这个指令提供了源代码包含功能，例如：

```
.. literalinclude:: example.py
```

结合上述的代码高亮，我们可以非常方便展示代码：

* 展示完整源代码，并且提供行号以及部分指定行高亮

```
.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:
```

* 展示某段类的方法

```
.. literalinclude:: example.py
   :pyobject: Timer.start
```

* 展示部分代码部分行

```
.. literalinclude:: example.py
   :lines: 1,3,5-10,20-
```

* 非常方便的代码对比高亮功能，可以用来对比两个代码文件：

```
.. literalinclude:: example.py
   :diff: example.py.orig
```

## 参考

* [Showing code examples](http://www.sphinx-doc.org/en/1.5/markup/code.html)
* [literalinclude](https://devopstutodoc.readthedocs.io/en/latest/documentation/doc_generators/sphinx/rest_sphinx/code/literalinclude/literalinclude.html)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://huataihuang.gitbook.io/cloud-atlas-draft/develop/doc/sphinx/sphinx_embed_code.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.