源代码与 API

源代码与 API#

1. 基础块语法高亮#

代码块包含语言标识符，用于确定代码的语言。该语言用于通过可用的 pygments 词法分析器进行语法高亮显示。

```python
from a import b
c = "string"
```

from a import b
c = "string"

添加语言词法分析器

您可以使用 pygments.lexers 入口点创建并注册自己的词法分析器，或者在 Sphinx 插件中使用 app.add_lexer 方法。

在原始 Markdown 块中显示反引号

如果您想在 Markdown 中显示反引号，可以通过将它们嵌套在更长的反引号中来实现。Markdown 会将最外层的反引号视为“原始”块的边界，而内部的所有内容都会显示出来。例如：

`` `hi` ``

````
```
hi
```
````

`hi`

```
hi
```

2. 行内语法高亮#

可以使用 attrs_inline 插件为行内代码应用语法高亮：

Inline Python code `a = "b"`{l=python}

Inline Python code a = "b"

3. 行号与高亮显示特定行#

要为每个词法分析器名称设置行号显示的全局默认值，可以使用 myst_number_code_blocks 配置选项。例如，使用：

myst_number_code_blocks = ["typescript"]

将默认对所有使用 typescript 词法分析器的代码块显示行号。

```typescript
type MyBool = true | false;

interface User {
  name: string;
  id: number;
}
```

type MyBool = true | false;

interface User {
  name: string;
  id: number;
}

要为特定代码块应用行号显示和高亮，可以使用 attrs_block 插件：

{lineno-start=1 emphasize-lines="2,3"}
```python
a = 1
b = 2
c = 3
```

a = 1
b = 2
c = 3

4. 添加标题#

使用 code-block directive，可以为代码块添加标题以及其他选项：

```{code-block} python
:caption: This is a caption
:emphasize-lines: 2,3
:lineno-start: 1

a = 1
b = 2
c = 3
```

This is a caption#

a = 1
b = 2
c = 3

以下选项被识别：

代码块选项

linenos : flag: 启用为代码块显示行号
lineno-start : integer: 代码块的起始行号（linenos 会自动启用）
emphasize-lines：以逗号分隔的整数列表: 高亮显示指定行
caption : string: The caption for the code block
force : flag: 允许忽略高亮显示中的小错误
name : string: 代码块的名称，可以在文档的其他地方引用
class : string: 应用于代码块的类

参见

Sphinx 文档

5. 从文件包含代码#

可以使用 literalinclude directive 从文件中包含较长的代码片段：

```{literalinclude} examples/example.py
```

"""An example Python file."""


# start example
class MyClass:
    """An example class."""

    def __init__(self, x: int, y: int):
        """An example method."""
        self.x = x
        self.y = y


# end example

a = 1

文件名通常相对于当前文件的路径。但是，如果它是绝对路径（以 / 开头），则相对于顶级源目录。

要仅选择文件的某一部分，可以使用 lines、pyobject 或 start-after 和 end-before 选项：

```{literalinclude} examples/example.py
:start-after: start example
:end-before: end example
```

class MyClass:
    """An example class."""

    def __init__(self, x: int, y: int):
        """An example method."""
        self.x = x
        self.y = y

参见

Sphinx 文档

6. 记录整个 API#

Sphinx 和 MyST 提供了分析源代码并自动生成 API 文档和可引用链接的功能。

可以使用 sphinx.ext.autodoc（见下文），但它本身并不与 MyST Markdown 兼容，因此推荐使用 sphinx-autodoc2 扩展。

6.1. `sphinx-autodoc2`#

sphinx-autodoc2 是 Sphinx 插件，提供了集成的方式来记录 Python API。

与 sphinx.ext.autodoc 不同，sphinx-autodoc2 对源代码进行静态（而非动态）分析，集成了完整的包文档记录，并且允许在 RestructureText 和 MyST 中编写文档字符串。

auto_mode 将自动生成完整的 API 文档，如 API Reference 所示。

或者，可以使用 autodoc2-object 指令为单个对象生成文档。要在 MyST 文档中嵌入，应指定 MyST render_plugin，例如：

```{autodoc2-object} myst_parser.sphinx_ext.main.setup_sphinx
render_plugin = "myst"
no_index = true
```

myst_parser.sphinx_ext.main.setup_sphinx(app: sphinx.application.Sphinx, load_parser: bool = False) → None[源代码]

初始化 Sphinx 中的所有设置和转换。

参数:

app -- Sphinx 应用程序对象。
load_parser -- Whether to load the parser.

This can be referenced elsewhere in the document using the :py:obj: role, or a # link (see cross-referencing).

- {py:obj}`myst_parser.sphinx_ext.main.setup_sphinx`
- [](#myst_parser.sphinx_ext.main.setup_sphinx)

Additionally, summaries of multiple objects can be generated using the autodoc2-summary directive:

```{autodoc2-summary}
:renderer: myst

~myst_parser.sphinx_ext.main.setup_sphinx
~myst_parser.sphinx_ext.main.create_myst_config
```

`setup_sphinx`	初始化 Sphinx 中的所有设置和转换。
`create_myst_config`	Create the myst config object and add it to the sphinx environment.

Using MyST docstrings#

sphinx-autodoc2 can be configured to use MyST docstrings (rather than RestructureText), for the entire project or select objects, by setting the autodoc2_docstring_parser_regexes configuration option:

autodoc2_docstring_parser_regexes = [
    # this will render all docstrings as Markdown
    (r".*", "myst"),
    # this will render select docstrings as Markdown
    (r"mypackage\.mymodule\..*", "myst"),
]

For example:

```{autodoc2-object} myst_parser.setup
render_plugin = "myst"
no_index = true
docstring_parser_regexes = [
    ["myst_parser\\.setup", "myst"],
]
```

myst_parser.setup(app)[源代码]: Initialize the Sphinx extension.

6.2. `sphinx.ext.autodoc`#

Sphinx extension autodoc also can generate documentation for Python objects. However, because it is hard-coded to generate RestructureText, the special eval-rst directive needs to be used:

```{eval-rst}
.. autofunction:: myst_parser.sphinx_ext.main.setup_sphinx
    :noindex:
```

myst_parser.sphinx_ext.main.setup_sphinx(app: Sphinx, load_parser: bool = False) → None[源代码]