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

Question

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

该协议的工作方式如下：

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

其中'command id'是单个字符，id和参数之间没有空格。

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

我能得到的最好结果是使用了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;
}

查看how to add a custom style to the RTD theme的详细信息。

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);
}