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

Create usage documentation for a serialized arguments interface

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

协议是这样工作的:

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 提供的主题,但这不是必需的。

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

例如在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);
}