Contribuir a la documentación de TensorFlow

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

Algunos proyectos de TensorFlow mantienen los 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 responsable del mantenimiento para contribuir.

Para participar en la comunidad de documentos de TensorFlow:

Referencia API

Para obtener más información, utilice 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 obtener una vista previa (aproximadamente) utilizando cualquier vista previa de Markdown .

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 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 API

Referencia de Python

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

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

Para generar los documentos de referencia de TensorFlow 2, use el script 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 tutoriales de TensorFlow están escritos como archivos Markdown y cuadernos interactivos de Jupyter . Los cuadernos se pueden ejecutar en su navegador utilizando Google Colaboratory . Los documentos narrativos en tensorflow.org se crean a partir de la rama master tensorflow/docs . Las versiones anteriores están disponibles en GitHub en las ramas de versión rX.x

Cambios simples

La forma más sencilla de realizar actualizaciones sencillas de la documentación de los archivos 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 de archivos, 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 Git local

Para ediciones de varios archivos o actualizaciones más complejas, es mejor utilizar 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 configuras un proyecto local.

Bifurca el repositorio de tensorflow/docs

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

Clona tu repositorio

Descargue una copia de su repositorio de documentos/ username remoto a 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 ú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)

Para 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 el cambio de su 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 contribuyentes 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 fusionará en el repositorio de documentos ascendente de TensorFlow.

Hay un paso de publicación independiente para actualizar tensorflow.org desde el repositorio de GitHub. Normalmente, los cambios se agrupan en lotes y el sitio se actualiza con un ritmo 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 cuaderno antes de enviar una solicitud de extracción.

Google Colaboratory es un entorno de notebook alojado que facilita la edición y ejecución de la documentación del notebook. 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

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

Formateo del cuaderno

Una herramienta de formato de cuaderno hace que las diferencias de origen del cuaderno de Jupyter sean consistentes y más fáciles de revisar. Dado que los entornos de creación de cuadernos difieren con respecto a la salida de archivos, sangría, metadatos y otros campos no especificados; nbfmt utiliza valores predeterminados obstinados con preferencia por el flujo de trabajo 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 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 utiliza 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 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 los documentos de TensorFlow .

Descargue archivos de cuaderno 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 Colab-GitHub

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

  1. En su repositorio username bifurcado /docs, 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 para guardar debe vincularse al repositorio y a la rama correspondientes. Agregue 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 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 tensorflow/docs-l10n . Envíe 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 fielmente posible. Dicho esto, las traducciones están escritas para las comunidades a las que sirven. Si la terminología, redacción, estilo o tono en inglés no se traducen a otro idioma, utilice una traducción apropiada para el lector.

El apoyo lingüístico está determinado por una serie de factores que incluyen, entre otros, métricas y demanda del sitio, apoyo de la comunidad, dominio del inglés , 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 contribuyentes de código abierto. Estos no se publican en tensorflow.org.