Articles of documentación de

Mostrar * solo * docstring en la documentación de Sphinx

Sphinx tiene una función llamada automethod que extrae la documentación de la cadena de documentación de un método y la incrusta en la documentación. Pero no solo incrusta la cadena de documentación, sino también la firma del método (nombre + argumentos). ¿Cómo puedo incrustar solo la cadena de documentación (excluyendo la firma del método)? ref: […]

¿Cuál es la forma correcta de documentar un parámetro de ** kwargs?

Estoy usando sphinx y el complemento autodoc para generar documentación de API para mis módulos de Python. Aunque puedo ver cómo documentar bien parámetros específicos, no puedo encontrar un ejemplo de cómo documentar un parámetro de **kwargs . ¿Alguien tiene un buen ejemplo de una manera clara de documentar esto?

¿Alguien ha usado Sphinx para documentar un proyecto de C ++?

Sphinx es una nueva herramienta de documentación para Python. Se ve muy bien. Lo que me pregunto es: ¿Qué tan adecuado es esto para documentar un proyecto de C ++? ¿Existen herramientas para convertir la documentación existente (por ejemplo, doxygen) al formato Sphinx? ¿Hay ejemplos en línea / descargables de proyectos de C ++ que […]

¿Hay alternativas reales a reStructuredText para la documentación de Python?

Estoy empezando un proyecto Python de código abierto en breve y estoy tratando de decidir por adelantado cómo escribir mis documentos. La respuesta obvia sería usar reStructuredText y Sphinx con autodoc, porque realmente me gusta la idea de simplemente documentar correctamente mi código en mis cadenas de documentos y luego hacer que Sphinx construya automáticamente […]

¿Qué poner en un módulo de documentación de python?

Bien, he leído tanto el PEP 8 como el PEP 257 , y he escrito muchas cadenas de documentación para funciones y clases, pero no estoy muy seguro de lo que debería incluir una cadena de documentación de módulos. Pensé que, como mínimo, debería documentar las funciones y clases que exporta el módulo, pero también […]

Python: ¿Cómo puedo definir en la esfinge qué archivos y directorios .rst deben usarse?

¿Cómo puedo definir en la esfinge qué archivos y directorios .rst deben usarse? Quiero incluir un generador de documentación automático en mi script de prueba / construcción / documentación. sphinx-quickstart se ejecutó en mi área de trabajo y creó un archivo index.rst. Como sphinx utiliza archivos de texto reestructurados para la documentación, navegué por el […]

¿Hay alguna forma de forzar un archivo Python para verificar la adherencia al estilo de documentación de Numpy?

Estoy trabajando en un proyecto que requiere documentación de Numpy. En mis días de Java, recuerdo haber tenido linters que verificaban la adherencia de Javadoc en Eclipse / IDEA; ¿Hay un equivalente que verifique la adherencia del estilo de documentación de Numpy? Sé sobre PEP257, pero no parece haber ninguna verificación específica para la documentación […]

Sphinx – tema personalizado no funciona

Tengo configurada la documentación de mi esfinge y quiero usar un tema personalizado. He leído las instrucciones del tema en el sitio web de la esfinge: http://www.sphinx-doc.org/en/stable/theming.html , pero no funciona. Tengo el nombre de mi tema igual que en el archivo conf.py y está en una carpeta zip en el mismo directorio, pero sigo […]

Python Sphinx hace referencia a nombres largos

Estoy trabajando en la documentación para mi módulo de Python (usando Sphinx y reST), y estoy descubriendo que al hacer referencias cruzadas con otros objetos de Python (módulos, clases, funciones, etc.) el nombre completo del objeto termina siendo increíblemente largo. A menudo es más de 80 caracteres, lo que me gustaría evitar a toda costa. […]

¿Por qué CPython no utiliza `sphinx.autodoc` para la biblioteca estándar?

Estoy desarrollando una biblioteca de python y estoy usando sphinx.autodoc para generar la documentación, ya que creo que esta es una buena forma de no repetirte y de tener documentación y código de acuerdo. ¿En un comentario a Emit reStructuredText de sphinx autodoc? Aprendí que “el proceso de comstackción de CPython docs no tiene habilitado […]