Categorías
Python

Encontrar el Editor de código Python Perfecta

 

Tabla de Contenidos

  • Por qué documentar su código es tan importante
  • Al comentar vs Documentar CodeBasics de comentar Código Tipo CodeCommenting través Hinting (Python 3.5 +)
  • Fundamentos de comentar Código
  • Al comentar Código Tipo mediante Hinting (Python 3.5 + )
  • Documentar su base de código Python usando Antecedentes DocstringsDocstrings BackgroundDocstring TypesDocstring formatos
  • Las cadenas de documentación
  • docstring Tipos
  • docstring formatos
  • documentación de sus Python ProjectsPrivate ProjectsShared ProjectsPublic y Open Source ProjectsDocumentation Herramientas y Recursos
  • proyectos privados
  • proyectos compartidos
  • pública y de código abierto Proyectos
  • Herramientas de Documentación y Recursos
  • ¿Por dónde empiezo?
  • Fundamentos de comentar Código
  • Al comentar Código Tipo mediante Hinting (Python 3.5 +) Antecedentes
  • Las cadenas de documentación Tipos
  • docstring
  • docstring Formatos
  • proyectos privados
  • proyectos compartidos
  • Pública y Open Source proyectos
  • Herramientas de Documentación y Recursos

Mira ahora Este tutorial tiene un vídeo relacionado curso creado por el equipo del real Python. Mira que junto con el tutorial escrito para profundizar su comprensión: Código Python Documentación : A Complete Guide

Bienvenido a su guía completa a la documentación de código Python. Ya sea que esté documentando un pequeño script o un proyecto grande, si usted es un principiante o sazonado Pythonista, esta guía cubre todo lo que necesita saber.

Hemos dividido esta guía en cuatro secciones principales:

no dude en leer a través de este tutorial de principio a fin o saltar a una sección que está interesado en él fue diseñado para funcionar en ambos sentidos..

Por qué documentar su código es tan importante

Con suerte, si estás leyendo este tutorial, usted ya conoce la importancia de documentar su código. Pero si no es así, permítaseme citar algo Guido me mencionó en una reciente PyCon:

“Código es más a menudo de lo leyó por escrito.”

Guido van Rossum

Cuando se escribe código, se escriben a dos audiencias principales: los usuarios y los desarrolladores (incluido usted mismo). Ambas audiencias son igualmente importantes. Si eres como yo, probablemente ha abierto hasta bases de código de edad y se preguntó a sí mismo: “¿Qué demonios estaba pensando?” Si tiene un problema al leer su propio código, imaginar lo que los usuarios u otros desarrolladores están experimentando cuando están tratando de utilizar o contribuir a su código.

Por el contrario, estoy seguro que le han acabado en una situación en la que quería hacer algo en Python y es exactamente lo que se ve como una gran biblioteca que puede hacer el trabajo. Sin embargo, cuando empiece a usar la biblioteca, busca ejemplos, escribir-ups, o incluso la documentación oficial sobre cómo hacer algo específico y no puede encontrar la solución de inmediato.

después de buscar, te das cuenta de que la documentación que falta o lo que es peor, falta por completo. Esta es una sensación frustrante que disuade del uso de la biblioteca, no importa cuán grande o eficiente es el código. Daniele Procida resume mejor esta situación:

“No importa lo bueno que su software es, porque si la documentación no es lo suficientemente bueno, la gente no lo uso.

Daniele Procida

En esta guía, aprenderá desde cero cómo documentar correctamente su código Python desde el más pequeño de scripts a la más grande de proyectos de Python para ayudar a prevenir a sus usuarios de haberse sentido demasiado frustrado para utilizar o contribuyen a su proyecto. Al comentar

vs Código Documentar

Antes de que podamos entrar en cómo documentar su código Python, es necesario distinguir la documentación de hacer comentarios.

En general, al comentar está describiendo su código a / para los desarrolladores. El público principal intención es los mantenedores y desarrolladores del código Python. En conjunción con el código bien escrito, comenta ayuda a guiar al lector a entender mejor su código y su propósito y diseño:

“Código se explica cómo hacerlo; Comentarios a decir por qué “.

Jeff Atwood (también conocido como codificación del horror) Código

La documentación está describiendo su uso y funcionalidad a sus usuarios. Si bien puede ser útil en el proceso de desarrollo, el principal público objetivo son los usuarios. La siguiente sección describe cómo y cuándo comentar su código.

Fundamentos de comentar Código

comentarios están creado en Python usando el signo de número (#) y deben ser breves declaraciones de no más de un par de frases. Aquí hay un ejemplo simple:

def hello_world():
# A simple comment preceding a simple print statement
print("Hello World")

De acuerdo con PEP 8, comentarios debe tener una longitud máxima de 72 caracteres. Esto es cierto incluso si su proyecto cambia la longitud de línea máxima a ser mayor que la recomendada de 80 caracteres. Si un comentario va a ser mayor que el límite carácter de comentario, el uso de múltiples líneas para el comentario es apropiado:

def hello_long_world():
# A very long statement that just goes on and on and on and on and
# never ends until after it's reached the 80 char limit
print("Hellooooooooooooooooooooooooooooooooooooooooooooooooooooooo World")

Al comentar su código sirve para múltiples propósitos, incluyendo:

    Planificación

  • y la revisión: Cuando está desarrollando nuevas porciones de su código, puede ser apropiado a primeros comentarios uso como una forma de planificación, o para delimitar esa sección de código. Recuerde que debe eliminar estos comentarios una vez que la codificación real se ha implementado y revisado / probado: # Primer paso # Segundo paso # Tercer paso
  • Código

  • Descripción: Los comentarios pueden ser utilizados para explicar la intención de las secciones específicas de código: # intentar una conexión basada en la configuración anterior. Si no tiene éxito, # preguntar al usuario para los nuevos ajustes.
  • algorítmico Descripción: Cuando se utilizan algoritmos complicados, especialmente queridos, puede ser útil para explicar cómo funciona el algoritmo o cómo se implementa dentro de su código. También puede ser apropiado para describir por qué un algoritmo específico fue seleccionado sobre otro # Usando rápida tipo de mejoras de rendimiento
  • Etiquetado:. El uso de etiquetado puede ser utilizado para las secciones de etiquetas específicas de código en la que se ubican los problemas o áreas de mejora conocidos. Algunos ejemplos son: ERROR, ARREGLAME, y TODO # TODO:. Agregar condición para cuando val es Ninguno

Planificación y revisión: Cuando está desarrollando nuevas partes de su código, puede ser apropiado a primeros comentarios uso como forma de planificar o esbozar esa sección de código. Recuerde que debe eliminar estos comentarios una vez que la codificación real se ha implementado y revisado / probado:

# First step
# Second step
# Third step

Código Descripción: Los comentarios pueden ser utilizados para explicar la intención de las secciones específicas de código:

# Attempt a connection based on previous settings. If unsuccessful,
# prompt user for new settings.

algorítmico Descripción: Cuando algoritmos son usados, especialmente los complicados, que pueden ser útiles para explicar cómo funciona el algoritmo o cómo se implementa dentro de su código. También puede ser apropiado para describir por qué un algoritmo específico fue seleccionado sobre otro.

# Using quick sort for performance gains

Tagging: El uso de etiquetado puede ser utilizado para las secciones de etiqueta de código específica donde se encuentran problemas o áreas de mejora conocidos. Algunos ejemplos son: ERROR, ARREGLAME, y TODO.

# TODO: Add condition for when val is None

comentarios al código debe ser breve y concentrado. Evitar el uso de los comentarios largos cuando sea posible. Además, se debe utilizar los siguientes cuatro reglas esenciales según lo sugerido por Jeff Atwood:

guardar comentarios lo más cerca posible del código que se está describiendo como sea posible. Los comentarios que no están cerca de su código que describe están frustrando al lector y fácilmente perderse cuando se hacen cambios.

no utilice un formato complejo (por ejemplo, tablas o figuras ASCII). Complejo de formatear conduce a distraer contenido y puede ser difícil de mantener en el tiempo.

no incluyen información redundante. Suponga el lector del código tiene un conocimiento básico de los principios de programación y sintaxis del lenguaje.

diseño de su código de comentar en sí. La forma más fácil de entender el código es mediante la lectura de la misma. Al diseñar su código usando claras fácil de entender conceptos, el lector será capaz de conceptualizar rápidamente su intención.

Recuerde que los comentarios están diseñados para el lector, incluido usted mismo, a la guía de ayuda en la comprensión de la finalidad y el diseño del software. Al comentar

Código Tipo mediante Hinting (Python 3.5 +)

Tipo insinuando se añadió a Python 3.5 y es una forma adicional para ayudar a los lectores de su código. De hecho, se tarda cuarta sugerencia de Jeff desde arriba al siguiente nivel. Se permite al desarrollador diseñar y explicar partes de su código sin comentar. Aquí está un ejemplo rápido:

def hello_name(name: str) -> str:
return(f"Hello {name}")

De examinar el tipo de insinuación, se puede decir inmediatamente que la función espera el nombre de entrada sea de un tipo str, o una cadena. También se puede decir que el resultado esperado de la función será de un tipo str, o una cadena, también. Mientras que el tipo insinuando ayuda a reducir los comentarios, tener en cuenta que al hacerlo también se puede hacer un trabajo extra cuando se va a crear o actualizar su documentación del proyecto.

Puede obtener más información sobre el tipo y una sugerencia de comprobación de tipos de este video creado por Dan Bader.

Documentar su base de código Python usando cadenas de documentación

Ahora que hemos aprendido acerca de comentar, tomemos una profunda inmersión en la documentación de una base de código Python. En esta sección, usted aprenderá acerca de las cadenas de documentación y la forma de utilizarlos para la documentación. Esta sección se divide en las siguientes subsecciones: Antecedentes

Las cadenas de documentación

documentar su código Python está todo centrado en las cadenas de documentación. Éstos están incorporados en las cadenas que, cuando está configurado correctamente, pueden ayudar a sus usuarios y usted mismo con la documentación del proyecto. Junto con las cadenas de documentación, Python también tiene la función de ayuda incorporada () que imprime los objetos cadena de documentación de la consola. Aquí está un ejemplo rápido:

>>> help(str)
Help on class str in module builtins:

class str(object)
| str(object='') -> str
| str(bytes_or_buffer[, encoding[, errors]]) -> str
|
| Create a new string object from the given object. If encoding or
| errors are specified, then the object must expose a data buffer
| that will be decoded using the given encoding and error handler.
| Otherwise, returns the result of object.__str__() (if defined)
| or repr(object).
| encoding defaults to sys.getdefaultencoding().
| errors defaults to 'strict'.
# Truncated for readability

Cómo se genera esta salida? Ya que todo en Python es un objeto, puede examinar el directorio del objeto usando el comando dir (). Vamos a hacer eso y ver lo que encontró:

>>> dir(str)
['__add__', ..., '__doc__', ..., 'zfill'] # Truncated for readability

Dentro de ese directorio de salida, hay una interesante propiedad, __doc__. Si examina esa propiedad, descubrirá esto:

>>> print(str.__doc__)
str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors are specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.

Voilà! Usted ha encontrado donde se almacenan cadenas de documentación dentro del objeto. Esto significa que se pueden manipular de este inmueble directamente. Sin embargo, existen restricciones para las órdenes internas:

>>> str.__doc__ = "I'm a little string doc! Short and stout; here is my input and print me for my out"
Traceback (most recent call last):
File "", line 1, in
TypeError: can't set attributes of built-in/extension type 'str'

Cualquier otro objeto personalizado puede ser manipulado:

def say_hello(name):
print(f"Hello {name}, is it me you're looking for?")

say_hello.__doc__ = "A simple function that says hello... Richie style"
>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
A simple function that says hello... Richie style

Python tiene una característica más que simplifica la creación cadena de documentación. En lugar de manipular la propiedad __doc__ directamente, la colocación estratégica de la cadena literal directamente debajo del objeto se ajusta automáticamente el valor __doc__. Esto es lo que sucede con el mismo ejemplo anterior:

def say_hello(name):
"""A simple function that says hello... Richie style"""
print(f"Hello {name}, is it me you're looking for?")
>>> help(say_hello)
Help on function say_hello in module __main__:

say_hello(name)
A simple function that says hello... Richie style

hay que ir! Ahora usted entiende el fondo de las cadenas de documentación. Ahora es el momento de aprender sobre los diferentes tipos de cadenas de documentación y la información que deben contener. Tipos convenciones

docstring

cadena de documentación se describen dentro de PEP 257. Su finalidad es proporcionar a los usuarios una breve descripción del objeto. Deben mantenerse lo suficientemente concisa para que sea fácil de mantener, pero siendo lo suficientemente elaborada para los nuevos usuarios a entender su propósito y cómo utilizar el objeto documentado.

En todos los casos, las cadenas de documentación debe utilizar la cita triple doble ( «» «) formato de cadena. Esto se debe hacer si la cadena de documentación es multi-revestida o no. Como mínimo, una cadena de documentación debe ser un resumen rápido de lo que sea que usted está describiendo y debe estar contenido en una sola línea: docstrings alineados-Multi

"""This is a quick summary line used as a description of the object."""

se utiliza para más elaborada en el objeto más allá del resumen Todas las cadenas de documentación multi-revestido tienen las siguientes partes:.

  • uno -line línea de resumen
  • Una línea en blanco de continuar el resumen
  • Cualquier elaboración adicional para la cadena de documentación
  • Otra línea en blanco

"""This is the summary line

This is the further elaboration of the docstring. Within this section,
you can elaborate further on details as appropriate for the situation.
Notice that the summary and the elaboration is separated by a blank new
line.
"""

# Notice the blank line above. Code should continue on this line.

Todas las cadenas de documentación deben tener la misma longitud de caracteres máx como comentarios (72 caracteres). las cadenas de documentación pueden ser divididos en tres categorías principales:

  • Clase docstrings: clase y métodos de la clase
  • del paquete y módulo docstrings: Paquetes, módulos y funciones
  • script docstrings: Scr ipt y funciones

Clase docstrings

Clase cadenas de documentación se crean para la clase en sí, así como cualquiera de los métodos de clase. Las cadenas de documentación se colocan inmediatamente después del método de clase o tipo de sangría por un nivel: docstrings

class SimpleClass:
"""Class docstrings go here."""

def say_hello(self, name: str):
"""Class method docstrings go here."""

print(f'Hello {name}')

clase deben contener la siguiente información:

  • Un resumen breve de su finalidad y el comportamiento
  • cualquier método público, junto con una descripción breve
  • Cualquier propiedades de clase (atributos)
  • todo lo relacionado con la interfaz para subclassers, si la clase está destinado a ser subclase

la clase parámetros de constructor deben ser documentados dentro de la cadena de documentación método de clase __init__. Los métodos individuales se deben documentar el uso de sus docstrings individuales. docstrings método de clase deben contener lo siguiente: Descripción breve

  • A de lo que el método es y para qué se usa para
  • Todos los argumentos (obligatorios y opcionales) que se pasan incluidos los argumentos de palabras clave
  • Etiqueta de los argumentos que se consideran opcional o tener un valor predeterminado
  • los posibles efectos secundarios que se producen al ejecutar el método
  • Cualquier excepción que se plantean
  • Cualquier restricción en cuando el método se puede llamar de

Let tomar un ejemplo simple de una clase de datos que representa un animal. Esta clase contendrá algunas propiedades de la clase, las propiedades de instancia, un __init__, y un método único ejemplo:

class Animal:
"""
A class used to represent an Animal

...

Attributes
----------
says_str : str
a formatted string to print out what the animal says
name : str
the name of the animal
sound : str
the sound that the animal makes
num_legs : int
the number of legs the animal has (default 4)

Methods
-------
says(sound=None)
Prints the animals name and what sound it makes
"""

says_str = "A {name} says {sound}"

def __init__(self, name, sound, num_legs=4):
"""
Parameters
----------
name : str
The name of the animal
sound : str
The sound the animal makes
num_legs : int, optional
The number of legs the animal (default is 4)
"""

self.name = name
self.sound = sound
self.num_legs = num_legs

def says(self, sound=None):
"""Prints what the animals name is and what sound it makes.

If the argument `sound` isn't passed in, the default Animal
sound is used.

Parameters
----------
sound : str, optional
The sound the animal makes (default is None)

Raises
------
NotImplementedError
If no sound is set for the animal or passed in as a
parameter.
"""

if self.sound is None and sound is None:
raise NotImplementedError("Silent Animals are not supported!")

out_sound = self.sound if sound is None else sound
print(self.says_str.format(name=self.name, sound=out_sound))

paquete y módulo de cadenas de documentación

paquete docstrings se deben colocar en la parte superior del archivo de __init__.py del paquete. Esta cadena de documentación debe listar los módulos y sub-paquetes que son exportados por el paquete. docstrings

módulo son similares a las cadenas de documentación de clase. En lugar de las clases y los métodos de la clase siendo documentado, es ahora el módulo y las funciones que se encuentran en su interior. docstrings módulo se colocan en la parte superior del archivo, incluso antes de cualquier importación. docstrings módulo debe incluir lo siguiente: Descripción breve

  • A del módulo y su propósito
  • Una lista de las clases, a excepción, funciones, y cualesquiera otros objetos exportados por el módulo

La cadena de documentación para una función de módulo debe incluir los mismos elementos que un método de clase:

  • una descripción breve de lo que la función es y para qué se usa para
  • todos los argumentos (obligatorios y opcionales) que se pasan incluyendo argumentos clave
  • Etiquetar los argumentos que se consideran opcionales
  • los posibles efectos secundarios que se producen al ejecutar la función
  • Cualquier excepción que se plantean
  • Cualquier restricción en cuando la función puede ser llamada Scripts

script las cadenas de documentación

se considera que son ejecutables solo archivo ejecuta desde la consola. Las cadenas de documentación para los scripts se colocan en la parte superior del archivo y se deben documentar lo suficientemente bien como para que los usuarios puedan tener un conocimiento suficiente de cómo utilizar la secuencia de comandos. Debe ser utilizable para su mensaje “uso”, cuando el usuario pasa de forma incorrecta en un parámetro o utiliza la opción -h.

Si utiliza argparse, a continuación, se puede omitir la documentación parámetro específico, suponiendo correctamente ha documentado dentro del parámetro de ayuda de la función argparser.parser.add_argument. Se recomienda utilizar el __doc__ para el parámetro en el constructor Descripción de argparse.ArgumentParser. Echa un vistazo a nuestro tutorial en línea de comandos de análisis de Bibliotecas para más detalles sobre cómo utilizar argparse y otros programas de análisis de línea de comandos comunes.

Por último, cualquier importación personalizados o de terceros debe aparecer dentro de las cadenas de documentación para permitir a los usuarios saber qué paquetes se estimen necesarias para la ejecución del script. Aquí está un ejemplo de una secuencia de comandos que se utiliza simplemente para imprimir los encabezados de las columnas de una hoja de cálculo:

"""Spreadsheet Column Printer

This script allows the user to print to the console all columns in the
spreadsheet. It is assumed that the first row of the spreadsheet is the
location of the columns.

This tool accepts comma separated value files (.csv) as well as excel
(.xls, .xlsx) files.

This script requires that `pandas` be installed within the Python
environment you are running this script in.

This file can also be imported as a module and contains the following
functions:

* get_spreadsheet_cols - returns the column headers of the file
* main - the main function of the script
"""

import argparse

import pandas as pd

def get_spreadsheet_cols(file_loc, print_cols=False):
"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
The file location of the spreadsheet
print_cols : bool, optional
A flag used to print the columns to the console (default is
False)

Returns
-------
list
a list of strings used that are the header columns
"""

file_data = pd.read_excel(file_loc)
col_headers = list(file_data.columns.values)

if print_cols:
print("\n".join(col_headers))

return col_headers

def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument(
'input_file',
type=str,
help="The spreadsheet file to pring the columns of"
)
args = parser.parse_args()
get_spreadsheet_cols(args.input_file, print_cols=True)

if __name__ == "__main__":
main()

docstring Formatos

Usted puede haber notado que, a través de los ejemplos dados en este tutorial, no ha sido determinado formato con elementos comunes: argumentos, valores devueltos y atributos. Hay formatos docstrings específicos que pueden ser utilizados para ayudar a los analizadores cadena de documentación y los usuarios tienen un formato familiar y conocido. El formato utilizado dentro de los ejemplos de este tutorial son docstrings / de estilo SciPy NumPy. Algunos de los más comunes formatos son los siguientes:

La selección del formato de cadena de documentación es de usted, pero usted debe pegarse con el mismo formato en todo el documento / proyecto. Los siguientes son ejemplos de cada tipo para darle una idea de cómo cada aspecto de formato de documentación.

Google cadenas de documentación Ejemplo

"""Gets and prints the spreadsheet's header columns

Args:
file_loc (str): The file location of the spreadsheet
print_cols (bool): A flag used to print the columns to the console
(default is False)

Returns:
list: a list of strings representing the header columns
"""

reestructurado Ejemplo de texto Ejemplo

"""Gets and prints the spreadsheet's header columns

:param file_loc: The file location of the spreadsheet
:type file_loc: str
:param print_cols: A flag used to print the columns to the console
(default is False)
:type print_cols: bool
:returns: a list of strings representing the header columns
:rtype: list
"""

NumPy / SciPy Las cadenas de documentación Ejemplo

"""Gets and prints the spreadsheet's header columns

Parameters
----------
file_loc : str
The file location of the spreadsheet
print_cols : bool, optional
A flag used to print the columns to the console (default is False)

Returns
-------
list
a list of strings representing the header columns
"""

Epytext

"""Gets and prints the spreadsheet's header columns

@type file_loc: str
@param file_loc: The file location of the spreadsheet
@type print_cols: bool
@param print_cols: A flag used to print the columns to the console
(default is False)
@rtype: list
@returns: a list of strings representing the header columns
"""

documentación de sus proyectos Proyectos Python Python

vienen en todo tipo de formas, tamaños y propósitos. La forma en que documentar su proyecto debe adaptarse a su situación específica. Tenga en cuenta que los usuarios de su proyecto van a ser y adaptarse a sus necesidades. Dependiendo del tipo de proyecto, se recomiendan ciertos aspectos de la documentación. El diseño general del proyecto y su documentación debe ser el siguiente:

project_root/

├── project/ # Project source code
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py

Proyectos en general se puede subdividir en tres grandes tipos: privadas, compartidas y público / Open Source. proyectos

proyectos privados

privadas son proyectos destinados únicamente para uso personal y en general no son compartidos con otros usuarios o desarrolladores. La documentación puede ser bastante luz sobre estos tipos de proyectos. Hay algunas partes recomienda añadir, según sea necesario:

  • Léame: Un resumen breve del proyecto y su propósito. Incluya todos los requisitos especiales para la instalación o el funcionamiento del proyecto.
  • examples.py: Un archivo de script Python que da ejemplos sencillos de cómo utilizar el proyecto.

Recuerde, a pesar de que los proyectos privados están destinados para usted, usted está también considerado como un usuario. Piense en todo lo que puede ser confuso para usted en el camino y asegúrese de capturar los de cualquiera de los comentarios, cadenas de documentación, o el readme. proyectos

proyectos compartidos

compartidos son proyectos en los que colabora con algunas otras personas en el desarrollo y / o uso del proyecto. El “cliente” o usuario del proyecto sigue siendo uno mismo y los pocos que limitan el uso del proyecto así.

La documentación debe ser un poco más riguroso de lo que debe ser para un proyecto privado, principalmente para ayudar a los nuevos miembros a bordo a los colaboradores del proyecto o de alerta / usuarios de los nuevos cambios en el proyecto. Algunas de las partes recomienda añadir al proyecto son los siguientes:

  • Léame: Un resumen breve del proyecto y su propósito. Incluir algún requisito especial para instalar o hacer funcionar el proyecto. Además, añadir cualquier cambio importante ya que la versión anterior.
  • examples.py: Un archivo de script Python que da ejemplos sencillos de cómo utilizar los proyectos.
  • Cómo contribuir: Esto debe incluir cómo los nuevos contribuyentes al proyecto pueden comenzar a contribuir. proyectos

públicos y proyectos de código abierto

Públicas y Open Source son proyectos que están destinados a ser compartido con un gran grupo de usuarios y puede involucrar a los equipos de desarrollo grandes. Estos proyectos deben colocar tan alto de prioridad a la documentación del proyecto como el desarrollo real del proyecto en sí. Algunas de las partes recomienda añadir al proyecto son los siguientes:

  • Léame: Un resumen breve del proyecto y su propósito. Incluir algún requisito especial para instalar o hacer funcionar los proyectos. Además, añadir cualquier cambio importante ya que la versión anterior. Por último, añadir enlaces a más documentación, informes de errores, y cualquier otra información importante para el proyecto. Dan Bader ha reunido un gran tutorial sobre lo que todos deberían incluirse en el readme.
  • Cómo contribuir: Esto debe incluir cómo los nuevos contribuyentes a la ayuda del proyecto lata. Esto incluye el desarrollo de nuevas características, la fijación de los problemas conocidos, añadiendo documentación, la adición de nuevas pruebas, o la cobertura de cuestiones.
  • Código de Conducta

  • : define cómo otros colaboradores deben tratarse en el desarrollo o la utilización de su software. Esto también indica lo que sucederá si este código se rompe. Si está utilizando Github, una plantilla de código de conducta se puede generar con la fraseología recomendada. Para Open Source proyecta sobre todo, considerar la adición de esto.
  • licencia: Un archivo de texto plano que describe la licencia de su proyecto utiliza. Para Open Source proyecta sobre todo, considerar la adición de esto. docs
  • : Una carpeta que contiene documentación adicional. La siguiente sección describe con más detalle lo que debe incluirse y cómo organizar el contenido de esta carpeta.

Léame: Un resumen breve del proyecto y su propósito. Incluir algún requisito especial para instalar o hacer funcionar los proyectos. Además, añadir cualquier cambio importante ya que la versión anterior. Por último, añadir enlaces a más documentación, informes de errores, y cualquier otra información importante para el proyecto. Dan Bader ha reunido un gran tutorial sobre lo que todos deberían incluirse en el readme.

Cómo contribuir: Esto debe incluir cómo los nuevos contribuyentes al proyecto pueden ayudar. Esto incluye el desarrollo de nuevas características, la fijación de los problemas conocidos, añadiendo documentación, la adición de nuevas pruebas, o la cobertura de cuestiones.

Código de Conducta

: define cómo otros colaboradores deben tratarse unos a otros en el desarrollo o la utilización de su software. Esto también indica lo que sucederá si este código se rompe. Si está utilizando Github, una plantilla de código de conducta se puede generar con la fraseología recomendada. Para Open Source proyecta sobre todo, considerar la adición de esto.

licencia: archivo de texto plano A que describe la licencia de su proyecto utiliza. Para Open Source proyecta sobre todo, considerar la adición de esto. docs

: Una carpeta que contiene documentación adicional. La siguiente sección describe con más detalle lo que debe incluirse y cómo organizar el contenido de esta carpeta.

Las cuatro secciones principales de los documentos de la carpeta

Daniele Procida dieron una maravillosa charla PyCon 2017 y la posterior entrada en el blog sobre la documentación de los proyectos de Python. Menciona que todos los proyectos deben tener las siguientes cuatro secciones principales para ayudarle a enfocar su trabajo:

  • Tutorías: Lecciones que llevan al lector de la mano a través de una serie de pasos para completar unos proyectos (o ejercicio significativo). Orientada hacia el aprendizaje de usuario.
  • guías de cómo hacerlo: guías que llevan al lector a través de los pasos necesarios para resolver un problema común (recetas orientadas al problema).
  • Referencias: Las explicaciones que aclaran e iluminan un tema en particular. Orientado hacia la comprensión. Explicaciones
  • : descripciones técnicas de la maquinaria y cómo hacerlo funcionar (clases principales, funciones, APIs, y así sucesivamente). Piense Enciclopedia artículo.

La siguiente tabla muestra cómo todas estas secciones se relaciona con los demás, así como su objetivo general:

Al final, usted quiere asegurarse de que los usuarios tienen acceso a las respuestas a cualquier pregunta que puedan tener. Mediante la organización de su proyecto de esta manera, usted será capaz de responder a estas preguntas con facilidad y en un formato que será capaz de navegar rápidamente.

Herramientas de Documentación y Recursos

documentar su código, especialmente los grandes proyectos, puede ser desalentador. Afortunadamente, hay algunas herramientas fuera y referencias para ayudarle a empezar:

Junto con estas herramientas, hay algunas adicionales tutoriales, vídeos y artículos que pueden ser útiles cuando se está documentando su proyecto:

A veces, la mejor manera de aprender es a los demás imitan. Aquí están algunos grandes ejemplos de proyectos que la documentación de uso así:

  • Django: Docs (Fuente) Solicitudes
  • : Docs (Fuente)
  • click: Docs (Fuente)
  • pandas: Docs (Fuente)

Dónde Do ¿Empiezo?

La documentación de los proyectos tienen una progresión simple:

Si estás en una pérdida sobre dónde ir a continuación con su documentación, vistazo a donde su proyecto se encuentra ahora en relación con la progresión anteriormente. ¿Tiene alguna documentación? Si no, entonces empezar por ahí. Si tiene algún tipo de documentación, pero se echa en falta algunos de los archivos clave del proyecto, empezar añadiendo aquellos.

Al final, no se desanime o abrumado por la cantidad de trabajo requerido para la documentación de código. Una vez que comienza la documentación de su código, se hace más fácil para seguir adelante. Siéntase libre de comentar si tiene alguna pregunta o extender la mano al Equipo de pitón real en las redes sociales, y le ayudaremos.

Mira ahora Este tutorial tiene un vídeo relacionado curso creado por el equipo del Real Python. Mira que junto con el tutorial escrito para profundizar su comprensión: Código Python Documentación : Una guía completa

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *