---
doc_id: FmYjZdIfCMmW
description: "用 literalinclude 按注释标记或函数名引用 Python 文件的一部分。是一篇代码引用的演示文档。"
tags: [sphinx, literalinclude, python]
---

# literalinclude: 引用文件的一部分

`literalinclude` 在 MyST 里就是 ```` ```{literalinclude} <path> ```` 代码块, 选项和 reST 版本完全一样。路径相对于当前文档, 以 `/` 开头则相对于 `docs/source`。

下面所有例子都引用同目录的 [example.py](example.py)。

## 用注释标记区间 (推荐)

在 Python 文件里用一对注释标记区间:

```python
# --- begin: make-id
def make_id(n: int = 12) -> str:
    ...
# --- end: make-id
```

然后用 `:start-after:` 和 `:end-before:` 只引用中间的部分, 标记行本身不会出现:

````markdown
```{literalinclude} example.py
:language: python
:start-after: "# --- begin: make-id"
:end-before: "# --- end: make-id"
```
````

结果:

```{literalinclude} example.py
:language: python
:start-after: "# --- begin: make-id"
:end-before: "# --- end: make-id"
```

### 方法内部的区间, 去掉缩进

区间在方法里面时, 用 `:dedent:` 去掉多余的缩进, 再加上标题和行号:

````markdown
```{literalinclude} example.py
:language: python
:start-after: "# --- begin: put-body"
:end-before: "# --- end: put-body"
:dedent:
:caption: Store.put 的方法体
:linenos:
```
````

```{literalinclude} example.py
:language: python
:start-after: "# --- begin: put-body"
:end-before: "# --- end: put-body"
:dedent:
:caption: Store.put 的方法体
:linenos:
```

## 按函数名或类名引用 (不需要注释)

`:pyobject:` 按名字找到函数、类或方法, 文件怎么改都不用调整:

````markdown
```{literalinclude} example.py
:pyobject: Store.put
:emphasize-lines: 4
```
````

```{literalinclude} example.py
:pyobject: Store.put
:emphasize-lines: 4
```

## 引用仓库里其他位置的文件

路径可以指向 `docs/source` 之外的地方, 比如直接引用这个仓库的 Python 源码:

````markdown
```{literalinclude} ../../../../sanhe_me_kb/doc_id.py
:pyobject: new_doc_id
```
````

```{literalinclude} ../../../../sanhe_me_kb/doc_id.py
:pyobject: new_doc_id
```

## 选项速查

| 选项 | 作用 |
| :--- | :--- |
| `:start-after:` / `:end-before:` | 从某行之后 / 到某行之前 (不含标记行) |
| `:start-at:` / `:end-at:` | 从某行开始 / 到某行结束 (含标记行) |
| `:pyobject:` | 按 Python 函数 / 类 / 方法名引用 |
| `:lines:` | 按行号引用, 例如 `1,3,5-10`。文件一改就错位, 不推荐 |
| `:dedent:` | 去掉公共缩进 |
| `:emphasize-lines:` | 高亮某几行 (行号相对于引用出来的片段) |
| `:caption:` / `:linenos:` | 标题 / 行号 |

```{note}
`{literalinclude}` 在 PyCharm 和 GitHub 的 Markdown 预览里只会显示成代码块里的原文, 只有 Sphinx 构建后才能看到引用的内容。
```