Create usage documentation for a serialized arguments interface

Question

I'm trying create the documentation to my project that has a specific communication protocol over serial interface.

The protocol works like this:

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

Where 'command id' is a single character, and there is no space between the id and the arguments.

I need to highlight each argument so the person who is reading it can identify where each argument starts and ends, and provide a definition to each argument later.

The best result I was able to get was using the glossary option from sphinx. The problem is that the glossary is global, so I cannot repeat any term from any command.

Here is the rst code with glossary solution

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. 

I've also tried using:

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

but with that, it is impossible to distinguish each argument in the output documentation. The is a way to alternate the color of each argument?

Also tried to alternate each argument with bold markup, but this gets override by the theme style if it is not the content block.

How can I reach a result like the one in the example, but having the glossary limited to line I am describing? The reference created with glossary between the term and its definition is not required.

I am using the theme provided by readthedocs, but that is not a requirement.

Answer 1

If I understand your question, you can do this with a custom style.

For example, in the Pyramid documentation glossary, create a new style rule:

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

See details of how to add a custom style to the RTD theme.

OP edit:

After this answer I discover how to do exactly what I wanted, here is the rst:

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. 

And here is the custom css file

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