Articles of docstring

Python rtype docstring / texto reestructurado para fábricas / selectores de clase

: rtype: especifica que este es el tipo de objeto devuelto Por lo tanto, cuando creo un objeto obj en el siguiente fragmento, recibo una advertencia del IDE, que cls is not callable , ya que el IDE espera, que cls es un object del tipo SomeAbstractClass , y quiero el propio SomeAbstractClass IDE tiene […]

Generar automáticamente la documentación de GitHub Wiki a partir de Docthings de Python

El título lo dice todo. Lo que imagino es tener cadenas de documentación para todos mis módulos, clases y funciones y de alguna manera navegar por el documento a través de github (wiki?). Además, el documento debe estar sincronizado con el código más reciente, lo que significa que debe actualizarse / volver a generarse en […]

¿Cómo evitar que PyCharm llene las cadenas de documentación?

Si agrego una cadena de documentos a un método utilizando la comilla triple, tan pronto como escribo un espacio después de la cita triple, PyCharm llenará la cadena de documentos con los parámetros que toma el método, y un valor de retorno, como: def fill_blank(self, direction): “”” :param direction: :return: “”” Busqué en las preferencias […]

Documentar el tipo de retorno `tuple` en una función docstring para sugerencias de tipo de PyCharm

¿Cómo puedo documentar que una función devuelve una tuple de tal manera que PyCharm pueda usarla para la tipificación de tipos? Ejemplo elaborado: def fetch_abbrev_customer_info(customer_id): “””Pulls abbreviated customer data from the database for the Customer with the specified PK value. :type customer_id:int The ID of the Customer record to fetch. :rtype:??? “”” … magic happens […]

Herramienta para verificar automáticamente el estilo de la cadena de documentos de acuerdo con PEP257

Las herramientas como pep8 pueden verificar el estilo del código fuente, pero no comprueban si las cadenas de documentación están ajustadas de acuerdo con pep257 , pep287 . ¿Hay tales herramientas? Actualizar Decidí implementar una herramienta de análisis estático por mi cuenta, ver: https://github.com/GreenSteam/pep257 En este momento, la mayor parte de pep257 está cubierta. El […]

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

Triple-doble cita vs Doble cita

¿Cuál es la forma preferida de escribir la cadena doc de Python? “”” o ” En el libro Dive Into Python , el autor proporciona el siguiente ejemplo: def buildConnectionString(params): “””Build a connection string from a dictionary of parameters. Returns string.””” En otro capítulo , el autor proporciona otro ejemplo: def stripnulls(data): “strip whitespace and […]

¿Cómo express varios tipos para un solo parámetro o un valor de retorno en las cadenas de documentos procesadas por Sphinx?

A veces, una función en Python puede aceptar un argumento de un tipo flexible. O puede devolver un valor de un tipo flexible. Ahora no puedo recordar un buen ejemplo de tal función en este momento, por lo tanto, estoy demostrando cómo se ve esa función con un ejemplo de juguete a continuación. Quiero saber […]

Formato de tabla csv en las cadenas de documentación de Python (Sphinx): múltiples líneas en una celda

Estoy usando Sphinx para documentar un proyecto de Python. Parece que hay un poco de inconsistencia con la directiva .. csv-table:: . El problema principal es una nueva línea en una celda. Y mi cuestionable salud mental. El siguiente código: .. csv-table:: :header: Header1, Header2, Header3 A, B, “These lines appear as one line, even […]

Cómo especificar diferentes tipos de retorno en la cadena de documentación de Python

Actualmente estoy escribiendo documentación para mi paquete de Python usando Sphinx y el complemento autodoc. Para un valor de retorno de una función, por ejemplo, puedo escribir :returns: int: count que le dice a sphinx que hay un valor de retorno de tipo int, conteo llamado Ahora tengo una función que me permite predecesores de […]