Referencia a parámetros en una cadena de documentación de Python
Uso Sphinx y la función de autodocs para asegurar que tengamos buena documentación en nuestro proyecto.
Así que estoy familiarizado conlistas de campos de información y estoy familiarizado con el usoreferencias cruzadas en nuestros docs.
Sin embargo, cuando escribo docstring para un método o función, me parece útil referirme a sus parámetros en el texto. Pero no parece haber una forma estructurada de hacer esto.
Podríamos decir por ejemplo
Use ``name`` to set the username
pero eso no tiene estructura, requiere que recuerdes qué estilo usaste para eso y si cambias de estilo debes cazar y eliminar todos los estilos incorrectos.
: param: no funciona fuera de una lista de campos de información, por lo que no puede escribir
Use :param:`name` to set the username
He visto el uso de algunos proyectos: parm: pero eso no está documentado y parece que no funciona. Así que deben tener alguna personalización.
Podría usar generic_roles pero me parece que estoy resolviendo un problema que estoy seguro que otros han encontrado.Así que espero que me haya perdido algo cegadoramente obvio.