Parâmetros de referência em um docstring em Python
Eu uso o Sphinx e o recurso autodocs para garantir que tenhamos bons documentos em nosso projeto.
Então estou familiarizado comlistas de campos de informação e eu estou familiarizado com o usoreferência cruzada em nossos docs.
No entanto, ao escrever docstring para um método ou função, acho útil referir-se a seus parâmetros no texto. Mas não parece haver uma maneira estruturada de fazer isso.
Nós poderíamos dizer, por exemplo
Use ``name`` to set the username
mas isso não tem estrutura, requer que você se lembre de qual estilo você usou para isso e se você mudar de estilo você tem que caçar e matar todos os estilos incorretos.
: param: não funciona fora de uma lista de campos de informação, então você não pode escrever
Use :param:`name` to set the username
Vi alguns projetos usarem: parm: mas isso não está documentado e parece não funcionar. Então eles devem ter alguma customização
Eu poderia usar generic_roles, mas parece que eu estou trabalhando em torno de um problema que tenho certeza que os outros encontraram.Então, espero ter perdido algo que é óbvio.