Articles of documentación de

Hacer un archivo PDF de la documentación de Python

El sitio oficial de Python ofrece descargas de documentación en PDF, pero están separados por capítulos. Descargué el código fuente y construí la documentación en PDF, que también eran archivos PDF separados. ¿Cómo puedo crear un archivo PDF desde el Makefile en el código fuente ? Creo que sería más conveniente leer. Si la concatenación […]

Cómo crear directivas personalizadas en Sphinx.

Actualmente estoy documentando una API de descanso escrita en Python. Toda la documentación del proyecto se crea con Sphinx, y para la API REST me gustaría crear algunas directivas especiales. Por ejemplo, digamos que tengo este recurso definido: @resource(“/user/”, method=”GET”) def user_details (email): “”” Returns detailed information about a user account. :resource GET: /user/ :query_param […]

¿Cómo puedo hacer referencia a un parámetro documentado de la función Python usando el marcado Sphinx?

Me gustaría hacer referencia a un parámetro de función previamente documentado en otra parte de una cadena de documentación de Python. Considere el siguiente ejemplo (ciertamente completamente artificial): def foo(bar): “””Perform foo action :param bar: The bar parameter “”” def nested(): “””Some nested function that depends on enclosing scope’s bar parameter. I’d like to reference […]

¿Cómo puedo configurar Sphinx para excluir condicionalmente algunas páginas?

Al generar documentación con Sphinx, me gustaría poder generar dos versiones de mi documentación: una que incluya todo y otra con solo un conjunto de páginas en particular. ¿Cuál es la mejor manera de lograrlo? Podría escribir un script de comstackción que mueva los archivos para lograr esto, pero sería muy bueno si hubiera una […]

Python-Sphinx: ¿Cómo documentar un archivo con funciones?

Tengo un archivo de python con funciones (lib.py), sin clases. Cada función tiene el siguiente estilo: def fnc1(a,b,c): ”’ This fonction does something. :param a: lalala :type a: str :param b: hahaha :type b: int :param c: hohoho :type c: int :rtype: int ”’ print a d = b + c return d Solo quiero […]

Combinando la documentación de Sphinx de múltiples subproyectos: manejo de índices, configuración de sincronización, etc.

Tenemos un proyecto de varios módulos documentado con la (excelente) Sphinx. Nuestra configuración no es diferente a la descrita en la lista de correo . En general, esto funciona muy bien ! Pero tenemos algunas preguntas acerca de hacerlo: Las tablas de contenidos del submódulo incluirán enlaces de índice. En el mejor de los casos, […]

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 […]