Literate Sphinx

Literate Sphinx 是一个为 文学编程 的 Sphinx 扩展。文学编程是一种将代码与文本交织在一起的方法。在文学编程中，代码的编写顺序是为了使人类读者理解，而不是为了计算机。

将文档源转换为人类可读文档的过程称为“编织”，而将计算机可读代码的过程称为“纠缠”。在此扩展中，编织过程是Sphinx的正常渲染过程。对于纠缠，此扩展提供了一个 tangle 构建器 —— 运行 make tangle 将在 _build/tangle 中输出计算机可读文件。

按照文学编程工具的惯例，此扩展也以文学编程风格 编写。

用法

通过运行 pip install literate-sphinx 安装扩展，并在您的 conf.py 中的 extensions 列表中添加 'literate_sphinx'。

代码块使用 literate-code 指令编写，其参数为块名。它具有以下选项

• lang：块的语言。默认为 conf.py 中指定的 highlight_language
• file：（不带值）如果块是文件，则存在。如果块是文件，则代码块名称
• class：要添加到HTML输出的类名列表，用空格分隔
• padding：当多个块具有相同的名称时，它们将按顺序写入。 padding 表示在此块和 上一个 同名块之间应该有多少空白行（如果有的话）。默认值为 conf.py 中指定的 default_chunk_padding，其默认值为 1。如果没有给出参数，则使用一个空白行。
• name：可以被 ref 或 numref 引用的目标名称。这不应与代码块名称混淆。

例如，在 ReST 中

.. literate-code:: code chunk name
   :lang: python

   def hello():
       print("Hello world")

或者在 Markdown 中使用 MyST 解析器

```{literate-code} code chunk name
:lang: python

def hello():
    print("Hello world")
```

要包含另一个代码块，请使用 {{ 和 }} 分隔符包围。每行只能有一个代码块。代码块将带有分隔符之前的所有内容作为前缀，并带有分隔符之后的所有内容作为后缀。

例如，

.. literate-code:: file.py
   :file:
   # before
   {{code chunk name}}
   # after

将生成一个名为 file.py 的文件，其内容为

# before
def hello():
    print("Hello world")
# after

和

.. literate-code:: file.py
   :file:
   # before
   class Hello:
       {{code chunk name}} # suffix
   # after

将生成

# before
class Hello:
    def hello(): # suffix
        print("Hello world") # suffix
# after

分隔符可以通过在 conf.py 中设置 literate_delimiters 选项来更改，它接受一个元组，其中第一个元素是左分隔符，第二个元素是右分隔符。例如

literate_delimiters = ('<<', '>>')

相同的代码块名称可以用于多个块；它们将以它们在文档中出现的顺序包含。如果文档跨越多个文件，它们将以 toctree 指令中定义的目录顺序进行处理。

除了将文档编织成计算机可读代码文件的 tangle 构建器之外，还有一个 annotated-tangle 构建器，它将计算机可读代码写入 HTML 文件，并用它们来自的块进行注释。您可以通过查看 此项目的注释编织 来查看示例。

---
maxdepth: 2
caption: "More:"
---
code

许可证

此软件可以在与 Sphinx 相同的许可证下重新分发。

:lang: text

Copyright Hubert Chathi <hubert@uhoreg.ca>

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

* Redistributions of source code must retain the above copyright
  notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright
  notice, this list of conditions and the following disclaimer in the
  documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SPDX-License-Identifier: BSD-2-Clause