Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Contribuir a la documentación de TensorFlow

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

Algunos proyectos de TensorFlow mantienen los archivos fuente de la documentación cerca del código en un repositorio separado, generalmente en un directorio docs/ . Vea 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 API

Para actualizar la documentación de referencia, busque el archivo fuente y edite la cadena de documentos del símbolo. Muchas páginas de referencia de API en tensorflow.org incluyen un enlace al archivo de origen donde se define el símbolo. Las cadenas de documentos admiten Markdown y se pueden obtener (aproximadamente) una vista previa con cualquier vista previa de Markdown .

Para obtener información sobre la calidad de la documentación de referencia y cómo involucrarse con los sprints de documentos y la comunidad, consulte los consejos de Documentos de la API de TensorFlow 2 .

Versiones y ramas

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

El paquete de TensorFlow predeterminado se rX.x 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.

Compilar 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 la 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 interactivos de Jupyter . Los blocs de notas se pueden ejecutar en su navegador mediante Google Colaboratory . Los documentos narrativos en tensorflow.org se compilan a partir de la rama master tensorflow / docs . Las versiones anteriores están disponibles en GitHub en las ramas de la versión rX.x

Cambios simples

La forma más sencilla de realizar actualizaciones de documentación sencillas en los archivos de Markdown es utilizar el editor de archivos basado en web de GitHub. Explore el repositorio de 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 del 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 extracción.

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

Bifurcar el repositorio de tensorflow / docs

En la página de GitHub de tensorflow / docs, haz clic en el botón Bifurcación para crear su propia copia de repositorio en su cuenta de GitHub. Una vez bifurcada, eres responsable de mantener actualizada la copia del repositorio con el repositorio de TensorFlow ascendente.

Clona tu repositorio

Descargue una copia de su username / repositorio de documentos remoto en su máquina local. Este es el directorio de trabajo donde realizarás 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 últimos cambios.

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. Crea una nueva rama

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 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. Cree una solicitud de extracción

Sube tu sucursal local a tu repositorio remoto de GitHub (github.com/ username / docs):

git push

Una vez que se completa el envío, 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 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 extracción, se combinará con el repositorio de documentos de TensorFlow ascendente.

Hay un paso de publicación independiente para actualizar tensorflow.org desde el repositorio de GitHub. Por lo general, los cambios se agrupan y el sitio se actualiza con una frecuencia 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 con formato incorrecto puede dañar el archivo. Asegúrese de probar el portátil 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 /classification.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 TensorFlow Docs.

Formateo del cuaderno

Una herramienta de formateo de cuadernos hace que las diferencias de origen de cuadernos de Jupyter sean consistentes y fáciles de revisar. Dado que los entornos de creación de blocs de notas difieren con respecto a la salida de archivos, sangría, metadatos y otros campos no especificados; nbfmt usa valores predeterminados obstinados con preferencia por el flujo de trabajo de Colab de documentos de TensorFlow. Para formatear un cuaderno, instale las herramientas del cuaderno de documentos de TensorFlow y ejecute 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, los cuadernos sin celdas de salida se ejecutan y prueban; 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 una nueva libreta, copie y edite la plantilla de libreta de documentos de TensorFlow .

Editar en Colab

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

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

Para crear una nueva libreta, copie y edite la plantilla de libreta de TensorFlow .

Flujo de trabajo Colab-GitHub

En lugar de descargar un archivo de cuaderno 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 username / documentos, use la interfaz de usuario web de GitHub para crear una nueva rama .
  2. Navegue hasta el archivo del cuaderno para editarlo.
  3. Abra el cuaderno en Google Colab: use el intercambio de URL o la extensión Abrir en Colab 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 de guardar debe vincularse al repositorio y la rama correspondientes. Agrega un mensaje de confirmación significativo.
  6. Después de guardar, busque su repositorio o el repositorio de tensorflow / docs , GitHub debería solicitarle que cree una solicitud de extracción.
  7. Los encargados de mantenimiento 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 tensorflow / docs-l10n . Envía solicitudes de extracción 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 del idioma 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, se eliminan los idiomas que no se mantienen. La compatibilidad con nuevos idiomas se anunciará en el blog de TensorFlow o Twitter .

Si su idioma preferido no es compatible, puede mantener una bifurcación comunitaria para los contribuyentes de código abierto. Estos no están publicados en tensorflow.org.