Help protect the Great Barrier Reef with TensorFlow on Kaggle Join Challenge

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 TensorFlow guardan los archivos fuente de documentación cerca del código en un repositorio separado, por lo general en un docs/ directorio. Véase el proyecto de CONTRIBUTING.md archivo o contactar con el desarrollador que aportar.

Para participar en la comunidad de documentos de TensorFlow:

Referencia de API

Para más detalles, utilice el TensorFlow documentos de la API guía colaborador . Esto demuestra cómo encontrar el archivo de origen y de edición del símbolo de cadena de documentación . Muchas páginas de referencia de API en tensorflow.org incluyen un enlace al archivo de origen donde se define el símbolo. Docstrings apoyan Markdown y pueden ser (aproximadamente) una vista preliminar usando cualquier previewer Markdown .

Versiones y ramas

El sitio de referencia de la API por defecto versión a la última estable binario Esto coincide con el paquete instalado con pip install tensorflow .

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

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

Compilar documentos de API

Referencia de Python

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

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

Para generar la documentación de referencia TensorFlow 2, utilice el tensorflow/tools/docs/generate2.py script:

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

TensorFlow guías y tutoriales están escritos como de rebajas archivos e interactivo Jupyter cuadernos. Cuadernos pueden ejecutarse en su navegador usando Google Colaboratorio . Los documentos narrativas sobre tensorflow.org se construyen a partir del tensorflow / docs master rama. Las versiones más antiguas están disponibles en GitHub en los rX.x ramas de liberación.

Cambios simples

La manera más fácil de hacer actualizaciones de la documentación directa de archivos de rebajas es el uso de GitHub editor de archivos basado en web . Navegar por la tensorflow / docs repositorio de rebajas para encontrar el que corresponde aproximadamente a la tensorflow.org estructura de la URL. En la esquina superior derecha de la vista del archivo, haga clic en el ícono 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

Por tensorflow / docs página de GitHub, haga clic en el botón Tenedor 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

Descargar una copia de su control remoto username / docs Repo a 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 en sincronía con tensorflow/docs , añadir una distancia aguas arriba 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 la cesión temporal de tensorflow/docs , crear una nueva rama de la rama local master:

git checkout -b feature-name

git branch  # List local branches
  master

* feature-name

2.Haz cambios

Editar archivos en su editor favorito y siga la guía de estilo de documentación 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 su sucursal local a tu repositorio GitHub remota (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. Si no es así, vaya a la tensorflow / docs Repo-o en su propio repo-GitHub y 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 a la publicación separada actualización tensorflow.org desde el repositorio 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 portátil con GitHub del editor de archivos basado en web , no es recomendable ya JSON malformación puede dañar el archivo. Asegúrese de probar el portátil antes de enviar una solicitud de extracción.

Google Colaboratorio es un entorno portátil alojado que facilita la documentación de edición y de ejecución portátil. Cuadernos en GitHub se cargan en Google Colab pasando la ruta de la URL Colab, por ejemplo, el portátil se encuentra en GitHub aquí: https://github.com/tensorflow/docs/blob/master/site/en/tutorials/keras /classification.ipynb
se pueden cargar en Google Colab en esta dirección: https://colab.research.google.com/github/tensorflow/docs/blob/master/site/en/tutorials/keras/classification.ipynb

Hay una Abrir en Colab extensión de Chrome que lleva a cabo esta sustitución URL cuando se navega un cuaderno en GitHub. Esto es útil cuando se abre un bloc de notas en su tenedor cesión temporal, ya que los botones superiores siempre se enlaza con la TensorFlow Docs master rama.

Formateo del cuaderno

Una herramienta de formateo de cuadernos hace que las diferencias de origen de cuadernos de Jupyter sean consistentes y más 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 utiliza los valores predeterminados obstinado con una preferencia por el docs TensorFlow Colab flujo de trabajo. Para dar formato a un cuaderno, instalar las herramientas de documentos notebook TensorFlow y ejecutar el nbfmt herramienta:

# 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 proyectos TensorFlow docs, cuadernos sin celdas de salida se ejecutan y probados; portátiles con celdas de salida guardadas se publican como está. nbfmt respeta el estado portátil y utiliza el --remove_outputs opción para eliminar explícitamente celdas de salida.

Para crear un nuevo portátil, copiar y editar la plantilla de documentos notebook TensorFlow .

Editar en Colab

Dentro del entorno de Google Colab, haga doble clic en las celdas para editar texto y bloques de código. Células de texto utilizan de rebajas y deben seguir la guía de estilo de documentos TensorFlow .

Descargar archivos portátiles de Colab con Archivo> Descargar .pynb. Cometer este archivo a su repo local de Git y enviar una solicitud de extracción.

Para crear un nuevo portátil, copiar y editar la plantilla de cuaderno 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 forma de horquilla username / docs Repo, utilice 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: utilizar el canje URL o el Abierto de extensión Colab Chrome.
  4. Edite el cuaderno en Colab.
  5. Confirmar los cambios a tu repositorio de 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, vaya a tu repositorio o la tensorflow / docs Repo, GitHub le preguntará si desea crear 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 los cuadernos y otros contenidos técnicos se encuentran en el tensorflow / docs-l10n GitHub repo. Envía una solicitud de extracción a través del proyecto TensorFlow GitLocalize .

Los documentos de inglés son la fuente de verdad y 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.

Soporte de idiomas está determinada por una serie de factores, incluyendo, pero no limitado a sitio métricas y la demanda, apoyo comunitario, dominio del Inglés , la preferencia por la audiencia, y otros indicadores. Dado que cada idioma admitido tiene un costo, se eliminan los idiomas que no se mantienen. Soporte para nuevos idiomas se dará a conocer 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.