Ссылка на параметры в строке документации Python

Question

Я использую Sphinx и функцию autodocs, чтобы у нас были хорошие документы в нашем проекте.

Итак, я знаком со списками информационных полей и знаком с использованием перекрестных ссылок в наших документах.

Однако при написании строки документации для метода или функции я считаю полезным ссылаться на их параметры в тексте. Но, похоже, не существует структурированного способа сделать это.

1. Мы могли бы сказать, например,

   Use ``name`` to set the username
   

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

2. : param: не работает вне списка информационных полей, поэтому вы не можете писать

   Use :param:`name` to set the username
   

3. Я видел, как некоторые проекты используют:parm: но это не задокументировано и, похоже, не работает. Таким образом, они должны иметь некоторые настройки

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

Надеюсь, я только что пропустил что-то ослепительно очевидное.

Answer 1

Вы можете написать собственное расширение, используя autodoc-process-docstring - это действительно просто.

Ищите расширение для :param: и заменить его на ваш выбор стиля.