为序列化参数接口创建使用文档

Question

我正在尝试为我的项目创建文档，该项目在串行接口上具有特定的通信协议。

协议是这样工作的：

Request data: 'command id''argument1''argument2'
Response: 'command id''response'

其中'command id'为单个字符，id和arguments之间没有space

我需要突出显示每个论点，以便阅读它的人可以识别每个论点的开始和结束位置，并在以后为每个论点提供定义。

我能得到的最好结果是使用 sphinx 的 glossary 选项。问题是词汇表是全球性的，所以我不能重复任何命令中的任何术语。

这是 rst 代码和 glossary 解决方案

command: L (0x4C)
-----------------

Description: Example command.

Usage: :term:`L`\ :term:`argument1`\ :term:`argument2`
    .. glossary::
        
        L
            command identifier.

        argument1
            
            first argument1
        
        argument2
            
            second argument

Answer: :term:`L`\ :term:`response`
    .. glossary::

        L
            command identifier.

        response
            response example.

我也试过使用：

:samp: `L{argument1}{argument2}`

但是这样就无法区分输出文档中的每个参数。这是一种改变每个参数颜色的方法吗？

还尝试用粗体标记替换每个参数，但如果不是内容块，这会被主题样式覆盖。

我怎样才能达到示例中的结果，但 glossary 仅限于我描述的行？不需要在术语及其定义之间使用 glossary 创建的引用。

我正在使用 readthedocs 提供的主题，但这不是必需的。

Answer 1

如果我理解你的问题，你可以使用自定义样式来完成此操作。

例如在Pyramid documentation glossary中新建一个样式规则：

dl.glossary.docutils dt:nth-of-type(2n+1) {
    background: #ffc0cb;
}

查看的详细信息。

OP 编辑：

在这个答案之后，我发现了如何做我想做的事情，这是第一个：

command: E (0x45)
-----------------

Description: Example command.

Usage: :samp:`{E}{argument1}{argument2}`
    .. rst-class:: cmdglossary

        | E: command identifier.
        | argument1: first argument1
        | argument2: second argument

Answer: :samp:`{E}`
    .. rst-class:: cmdglossary

        | E: command identifier.        
        | response: response example.

这里是自定义 css 文件

code.samp em:nth-of-type(2n+2) {
    background: #e7f2fa;
}

code.samp em{
    color: #2980B9;
}

.cmdglossary div.line:nth-of-type(2n+2) {
    background: rgb(231, 242, 250);
}

为序列化参数接口创建使用文档

Create usage documentation for a serialized arguments interface

python-sphinx

restructuredtext

glossary