Contribuir a la documentación de TensorFlow

TensorFlow agradece las contribuciones de documentación: si mejora la documentación, mejora la propia biblioteca de TensorFlow. La documentación en tensorflow.org se divide en las siguientes categorías:

Algunos proyectos de TensorFlow mantienen archivos fuente de documentación cerca del código en un repositorio separado, generalmente en un directorio docs/ . Consulte el archivo CONTRIBUTING.md del proyecto o comuníquese con el mantenedor para contribuir.

Para participar en la comunidad de documentos de TensorFlow:

Referencia de la API

Para obtener más información, use la guía para colaboradores de documentos de la API de TensorFlow . Esto le muestra cómo encontrar el archivo fuente y editar la cadena de documentación del símbolo . Muchas páginas de referencia de API en tensorflow.org incluyen un enlace al archivo fuente donde se define el símbolo. Las cadenas de documentos admiten Markdown y se pueden previsualizar (aproximadamente) con cualquier programa de vista previa de Markdown .

Versiones y ramas

La versión de referencia de la API del sitio tiene como valor predeterminado el último binario estable; esto coincide con el paquete instalado con pip install tensorflow .

El paquete TensorFlow predeterminado se crea a partir de la rama estable rX.x en el repositorio principal de tensorflow/tensorflow . La documentación de referencia se genera a partir de comentarios de código y cadenas de documentación en el código fuente para Python , C++ y Java .

Las versiones anteriores de la documentación de TensorFlow están disponibles como ramas rX.x en el repositorio de TensorFlow Docs. Estas ramas se agregan cuando se lanza una nueva versión.

Crear documentos de API

Referencia de Python

El paquete tensorflow_docs incluye el generador de los documentos de referencia de la API de Python . Instalar:

pip install git+https://github.com/tensorflow/docs

Para generar los documentos de referencia de TensorFlow 2, use el tensorflow/tools/docs/generate2.py :

git clone https://github.com/tensorflow/tensorflow tensorflow
cd tensorflow/tensorflow/tools/docs
pip install tensorflow
python generate2.py --output_dir=/tmp/out

documentación narrativa

Las guías y los tutoriales de TensorFlow están escritos como archivos Markdown y cuadernos Jupyter interactivos. Los cuadernos se pueden ejecutar en su navegador usando Google Colaboratory . Los documentos narrativos en tensorflow.org se crean a partir de la rama master de tensorflow/docs . Las versiones anteriores están disponibles en GitHub en las ramas de lanzamiento de rX.x

Cambios simples

La forma más fácil de realizar actualizaciones de documentación sencillas en los archivos de Markdown es usar el editor de archivos basado en la web de GitHub. Explore el repositorio tensorflow/docs para encontrar el Markdown que corresponde aproximadamente a la estructura de URL de tensorflow.org . En la esquina superior derecha de la vista de archivo, haga clic en el icono de lápiz para abrir el editor de archivos. Edite el archivo y luego envíe una nueva solicitud de extracción.

Configurar un repositorio de Git local

Para ediciones de varios archivos o actualizaciones más complejas, es mejor usar un flujo de trabajo de Git local para crear una solicitud de incorporación de cambios.

Los siguientes pasos de Git solo son necesarios la primera vez que configura un proyecto local.

Bifurcar el repositorio tensorflow/docs

En la página de GitHub de tensorflow/docs , haga clic en el botón Fork para crear su propia copia del repositorio en su cuenta de GitHub. Una vez bifurcado, usted es responsable de mantener su copia del repositorio actualizada con el repositorio TensorFlow ascendente.

Clona tu repositorio

Descargue una copia de su nombre de username remoto/repositorio de documentos en su máquina local. Este es el directorio de trabajo donde realizará cambios:

git clone git@github.com:username/docs
cd ./docs

Agregue un repositorio ascendente para mantenerse actualizado (opcional)

Para mantener su repositorio local sincronizado con tensorflow/docs , agregue un control remoto ascendente para descargar los cambios más recientes.

Agregar un control remoto:

git remote add upstream git@github.com:tensorflow/docs.git

# View remote repos
git remote -v
origin    git@github.com:username/docs.git (fetch)
origin    git@github.com:username/docs.git (push)
upstream  git@github.com:tensorflow/docs.git (fetch)
upstream  git@github.com:tensorflow/docs.git (push)

Actualizar:

git checkout master
git pull upstream master

git push  # Push changes to your GitHub account (defaults to origin)

Flujo de trabajo de GitHub

1. Crear una nueva sucursal

Después de actualizar su repositorio desde tensorflow/docs , cree una nueva rama desde la rama maestra local:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2. Haz cambios

Edite los archivos en su editor favorito y siga la guía de estilo de la documentación de TensorFlow .

Confirme su cambio de archivo:

# View changes
git status  # See which files have changed
git diff    # See changes within files

git add path/to/file.md
git commit -m "Your meaningful commit message for the change."

Agregue más confirmaciones, según sea necesario.

3. Crea una solicitud de extracción

Cargue su sucursal local en su repositorio remoto de GitHub ( username ):

git push

Una vez que se completa la inserción, un mensaje puede mostrar una URL para enviar automáticamente una solicitud de extracción al repositorio ascendente. De lo contrario, vaya al repositorio de tensorflow/docs , o a su propio repositorio, y GitHub le pedirá que cree una solicitud de extracción.

4. Revisión

Los mantenedores y otros colaboradores revisarán su solicitud de extracción. Participe en la discusión y realice los cambios solicitados. Cuando se apruebe su solicitud de incorporación de cambios, se fusionará con el repositorio de documentos de TensorFlow aguas arriba.

Hay un paso de publicación independiente para actualizar tensorflow.org desde el repositorio de GitHub. Por lo general, los cambios se agrupan en lotes y el sitio se actualiza con una cadencia regular.

Cuadernos interactivos

Si bien es posible editar el archivo JSON del cuaderno con el editor de archivos basado en web de GitHub, no se recomienda ya que un JSON mal formado puede dañar el archivo. Asegúrese de probar el cuaderno antes de enviar una solicitud de extracción.

Google Colaboratory es un entorno de bloc de notas alojado que facilita la edición y ejecución de la documentación del bloc de notas. Los cuadernos en GitHub se cargan en Google Colab pasando la ruta a la URL de Colab, por ejemplo, el cuaderno ubicado en GitHub aquí: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /clasificación.ipynb
se puede cargar en Google Colab en esta URL: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Hay una extensión Open in Colab Chrome que realiza esta sustitución de URL cuando se navega por un cuaderno en GitHub. Esto es útil al abrir un cuaderno en su bifurcación de repositorio, porque los botones superiores siempre se vinculan a la rama master de TensorFlow Docs.

Formato de cuaderno

Una herramienta de formato de notebook hace que las diferencias de origen de Jupyter Notebook sean consistentes y más fáciles de revisar. Dado que los entornos de creación de cuadernos difieren con respecto a la salida del archivo, la sangría, los metadatos y otros campos no especificados; nbfmt utiliza valores predeterminados obstinados con preferencia por el flujo de trabajo de TensorFlow docs Colab. Para formatear una libreta, instala las herramientas de la libreta de documentos de TensorFlow y ejecuta la herramienta nbfmt :

# Install the tensorflow-docs package:
$ python3 -m pip install -U [--user] git+https://github.com/tensorflow/docs

$ python3 -m tensorflow_docs.tools.nbfmt [options] notebook.ipynb [...]

Para los proyectos de documentos de TensorFlow, se ejecutan y prueban cuadernos sin celdas de salida; los cuadernos con celdas de salida guardadas se publican tal cual. nbfmt respeta el estado del cuaderno y usa la opción --remove_outputs para eliminar explícitamente las celdas de salida.

Para crear un nuevo cuaderno, copie y edite la plantilla del cuaderno de documentos de TensorFlow .

Editar en Colaboración

Dentro del entorno de Google Colab, haga doble clic en las celdas para editar bloques de texto y código. Las celdas de texto usan Markdown y deben seguir la guía de estilo de documentos de TensorFlow .

Descargue archivos de blocs de notas de Colab con Archivo > Descargar .pynb . Confirme este archivo en su repositorio Git local y envíe una solicitud de extracción.

Para crear un nuevo cuaderno, copie y edite la plantilla del cuaderno de TensorFlow .

Flujo de trabajo de Colab-GitHub

En lugar de descargar un archivo de notebook y usar un flujo de trabajo de Git local, puede editar y actualizar su repositorio de GitHub bifurcado directamente desde Google Colab:

  1. En su repositorio bifurcado de nombre de username /docs, use la interfaz de usuario web de GitHub para crear una nueva rama .
  2. Navegue hasta el archivo del cuaderno para editar.
  3. Abra el bloc de notas en Google Colab: use el intercambio de URL o la extensión Open in Colab de Chrome.
  4. Edite el cuaderno en Colab.
  5. Confirme los cambios en su repositorio desde Colab con Archivo > Guardar una copia en GitHub... . El cuadro de diálogo Guardar debe vincularse con el repositorio y la rama apropiados. Agregue un mensaje de confirmación significativo.
  6. Después de guardar, busque su repositorio o el repositorio tensorflow/docs , GitHub debería solicitarle que cree una solicitud de extracción.
  7. Los mantenedores revisan la solicitud de extracción.

Traducciones

El equipo de TensorFlow trabaja con la comunidad y los proveedores para proporcionar traducciones para tensorflow.org. Las traducciones de cuadernos y otro contenido técnico se encuentran en el repositorio de GitHub de tensorflow/docs-l10n . Envíe solicitudes de incorporación de cambios a través del proyecto TensorFlow GitLocalize .

Los documentos en inglés son la fuente de la verdad y las traducciones deben seguir estas guías lo más cerca posible. Dicho esto, las traducciones se escriben para las comunidades a las que sirven. Si la terminología, la redacción, el estilo o el tono en inglés no se traducen a otro idioma, utilice una traducción adecuada para el lector.

El soporte de idiomas está determinado por una serie de factores que incluyen, entre otros, las métricas y la demanda del sitio, el apoyo de la comunidad, el dominio del inglés , la preferencia de la audiencia y otros indicadores. Dado que cada idioma admitido tiene un costo, los idiomas no mantenidos se eliminan. La compatibilidad con nuevos idiomas se anunciará en el blog de TensorFlow o en Twitter .

Si su idioma preferido no es compatible, puede mantener una bifurcación comunitaria para colaboradores de código abierto. Estos no se publican en tensorflow.org.