Предупреждение о неизвестной пользовательской интерпретируемой текстовой роли

Вы должны различать 4 вещи: «роли», «директивы», «домены» и «опции».

Их отличает пунктуация, в сокращенном синтаксисе :role: и .. directive::. В полном синтаксисе (без пропуска домена) :domain:role: и .. domain:directive::. Наконец, «параметры» относятся к «директивам» и реже к «ролям», например,:

.. domain:directive::
    :option:

или

:domain:role:

Итак, что такое домен? В большинстве случаев это относится к контексту языка программирования, который имеет роли и специфичные для него директивы. (Обратите внимание, что боковая панель в документации для директив разделена на домены).

Сказав это, давайте посмотрим на заявленную проблему:

• в конце моего файла conf.py:

  rst_prolog = """
  .. role:: LaTeXLogo
  """
  

Мы сразу замечаем 3 вещи:

1. Используемая пунктуация предназначена для директивы, а не для роли.
2. Если вы проверите список директив (или ролей и доменов), директивы под названием LaTeXLogo нет...
3. ... и вы также не пишете :role:, потому что у каждой роли есть имя (слово :role: используется только для общих примеров).

Далее мы рассмотрим второй пример:

в некоторых из моих .rst файлов:

:LaTeXLogo:`LaTeX`

Теперь мы замечаем:

1. Используется синтаксис для роли.
2. В предыдущем примере LaTexLogo был "директивным аргументом"...
3. ... это теперь жнецы как роль.

В заключение, единственный случай, когда используется вышеизложенное, — это «Пользовательские роли интерпретируемого текста», которые имеют краткое описание синтаксиса в Спецификации разметки reStructuredText . Если копнуть глубже, общее описание дается в Роли интерпретируемого текста reStructuredText , с более конкретным определением в «Создание ролей интерпретируемого текста reStructuredText», где присутствует ограничение на использование нижнего регистра:

Зарегистрируйте роль

2. Добавьте запись в словарь ролей в docutils/parsers/rst/languages/en.py для роли, сопоставив английское имя с каноническим именем (оба в нижнем регистре).

Большинству пользователей reStructuredText, вероятно, не понадобится такая сложность. Это далеко за пределы начального уровня и граничит с определением DTD синтаксического анализатора docutils. Если вы, наконец, посмотрите на «Типы пользовательских атрибутов», дальнейшая спецификация объясняет возникшую у вас ошибку:

Пользовательские типы атрибутов

В reStructuredText имена пользовательских классов могут быть указаны с использованием (...) пользовательских интерпретируемых текстовых ролей. Docutils нормализует их, чтобы они соответствовали требованиям к именам HTML4.1 и CSS1.0 (регулярное выражение a-z*) посредством нормализации идентификатора.