Я использую Sphinx и функцию autodocs, чтобы гарантировать, что у нас есть хорошие документы в нашем проекте.
Итак, я знаком с списками информационных полей, и я знаком с использованием cross-referencing в наших документах.
Однако при написании docstring для метода или функции я считаю полезным ссылаться на их параметры в тексте. Но для этого не существует структурированного способа.
-
Можно сказать, например,
Use ``name`` to set the usernameно у вас нет структуры, вам нужно помнить, какой стиль вы использовали для этого, и если вы меняете стиль, вам нужно выследить и уничтожить все неправильные стили.
-
: param: не работает за пределами списка информационного поля, поэтому вы не можете писать
Use :param:`name` to set the username -
Я видел, как некоторые проекты используют: parm: но это не документировано и, похоже, не работает. Поэтому у них должна быть какая-то настройка
- Я мог бы использовать generic_roles, но мне кажется, что я работаю над проблемой, которую я уверен, что другие столкнулись.
Надеюсь, я только что пропустил что-то ослепительно очевидное.