RestructuredText в Sphinx и Docstrings: одинарные или двойные обратные кавычки или обратные тики

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

Это привело бы меня к написанию документации для метода f() ниже:

class A(B):

    def f(arg1, arg2):
        return B(arg1 + arg2 + self.index)

Как:

Takes two arguments, ``arg1` and ``arg2``, which are assumed to be objects
of type (or duck-type) `NiceClass`, and returns a new object of class `B`
with `B.something` assigned some hash of ``arg1`` and ``arg2``.

Было бы это правильно?

Во многих примерах кода, Sphinx и других, я вижу эквивалент B а также NiceClass заключенные в двойные обратные кавычки ("``B``" и "``NiceClass``").

Источник

1 ответ

Решение

Из документации Сфинкса:

Роль по умолчанию (`content`) не имеет специального значения по умолчанию. Вы можете использовать его для чего угодно, например, для имен переменных; использовать default_role значение конфигурации, чтобы установить его для известной роли.

Что касается личных предпочтений, при написании строк документации Python я использую интерпретированный текст (одинарные обратные кавычки) для имен Python и точечных путей, независимо от того, находятся ли они в области видимости в месте расположения строки документации. Так что в вашем случае я бы поставил arg1, arg2, NiceClass, B а также B.something все в одинарных кавычках, при желании добавляя соответствующие :class:, :mod: и т.д. роли.

Источник

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

В Markdown, согласно спецификации CommonMark, они эквивалентны:

  • Просмотр обычного текста -> Результаты рендеринга
  • `inline literal` -> inline literal
  • ``inline literal`` -> inline literal
  • ```inline literal``` -> inline literal

  • ...

    Это потому, что все они видны как обратная строка:

    Строка обратной апострофы - это строка из одного или нескольких обратных апострофов (`), не имеющая ни предшествующей, ни следующей за ней обратной кавычки.

В то время как в reStructuredText, окружающие одиночные и двойные обратные кавычки отличаются:

  • `interpreted text` -> результат рендеринга зависит от разных определений.

    Рендеринг и значение интерпретируемого текста зависят от предметной области или приложения. Его можно использовать для таких вещей, как элементы указателя или явная описательная разметка (например, идентификаторы программ).

  • ``inline literal`` -> inline literal

    Обычно отображается как моноширинный текст. Пробелы должны быть сохранены, но разрывов строк не будет.

Итак, в общем, двойные обратные кавычки reStructuredText окружают ``code`` в некоторой степени эквивалентен одиночной обратной кавычке Surround в Markdown `code`.

Источник
Другие вопросы по тегам