Создать документацию по использованию для сериализованного интерфейса аргументов - PullRequest
Новая
       45

Создать документацию по использованию для сериализованного интерфейса аргументов

0 голосов
/ 01 апреля 2019

Я пытаюсь создать документацию для моего проекта, которая имеет определенный протокол связи через последовательный интерфейс.

Протокол работает так: 

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

Где 'идентификатор команды' - это один символ, и между идентификатором и аргументами нет пробела.

Мне нужно выделить каждый аргумент, чтобы человек, который его читает, мог определить, где начинается и заканчивается каждый аргумент, и предоставить определение каждому аргументу позже.

Лучший результат, который мне удалось получить, это использование опции glossary от sphinx. Проблема в том, что глоссарий является глобальным, поэтому я не могу повторить ни одного термина из любой команды.

Вот код 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, но это не является обязательным требованием.

Заранее спасибо.

1 Ответ

1 голос
/ 01 апреля 2019

Если я понимаю ваш вопрос, вы можете сделать это с помощью собственного стиля.

Например, в глоссарии документации Pyramid создайте новое правило стиля: 

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

См. Подробности , как добавить собственный стиль в тему RTD .

Alternate background color for glossary entries

OP edit:

После этого ответа я узнаю, как делать именно то, что хотел, вот первое: 

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