docs.md

Cómo contribuir a la documentación de TensorFlow

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

• Referencia de la API: los documentos de referencia de la API se generan a partir de cadenas de documentos en el código fuente de TensorFlow.

• Documentación narrativa: se trata de tutoriales, guías y otros escritos que no forman parte del código de TensorFlow. Esta documentación está disponible en el repositorio de GitHub tensorflow/docs.

• Traducciones de la comunidad: son guías y tutoriales traducidos por la comunidad. Todas las traducciones de la comunidad se encuentran en el repositorio tensorflow/docs.

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

Si desea participar en la comunidad de documentos de TensorFlow, haga lo siguiente:

• Consulte el repositorio de GitHub tensorflow/docs.

• Siga la etiqueta docs en el Foro de TensorFlow.

Referencia de la API

Para obtener más información, utilice la guía para colaboradores de documentos de la API de TensorFlow. Allí se indica cómo encontrar el archivo fuente y editar la cadena de documentación del símbolo. Muchas páginas de referencia de la API en tensorflow.org incluyen un enlace al archivo fuente donde se define el símbolo. Las cadenas de documentos son compatibles con Markdown y es posible acceder a una vista previa (aproximada) con cualquier visor de Markdown.

Versiones y ramas

La versión de referencia de la API del sitio es, por defecto, la versión binaria estable más reciente, que coincide con el paquete instalado con pip install tensorflow.

El paquete TensorFlow predeterminado se genera a partir de la rama estable rX.x en el repositorio principal 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 de Python, C++ y Java.

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

Cómo crear documentos para la API

Nota: Este paso no es necesario para editar ni para acceder a una vista previa de las cadenas de documentos de la API, solo para generar el HTML que se usa en tensorflow.org.

Referencia de Python

El paquete tensorflow_docs incluye el generador de documentos de referencia de la API de Python. Instalación:

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

Nota: Este script utiliza el paquete de TensorFlow instalado para generar documentos y solo funciona con TensorFlow 2.x.

Documentación narrativa

Las guías y los tutoriales de TensorFlow se escriben como archivos Markdown y blocs de notas interactivos de Jupyter. Los blocs de notas se pueden ejecutar en un navegador si se usa Google Colaboratory. Los documentos narrativos de 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 actualizar la documentación de los archivos Markdown es usar el editor de archivos basado en la web de GitHub. Navegue por el repositorio tensorflow/docs para encontrar el archivo Markdown que se corresponde aproximadamente con la estructura de la URL de tensorflow.org. En la esquina superior derecha de la vista del archivo, haga clic en el icono del lápiz para abrir el editor de archivos. Edite el archivo y, a continuación, envíe una nueva solicitud de extracción.

Configure un repositorio de Git local

Para editar varios archivos o ejecutar actualizaciones más complejas, es mejor utilizar un flujo de trabajo de Git local para crear una solicitud de extracción.

Nota: Git es el sistema de control de versiones (VCS) de código abierto que se utiliza para hacer un seguimiento de los cambios en el código fuente. GitHub es un servicio en línea que proporciona herramientas de colaboración que funcionan con Git. Consulte la Ayuda de GitHub para configurar su cuenta de GitHub y empezar a trabajar.

Los siguientes pasos de Git solo son necesarios cuando se configura un proyecto local por primera vez.

Bifurque el repositorio tensorflow/docs

En la página de GitHub de tensorflow/docs, haga clic en el botón Fork (Bifurcar) para crear su propia copia del repositorio en su cuenta de GitHub. Una vez que se haya efectuado la bifurcación, usted será responsable de mantener su copia del repositorio actualizada con el repositorio ascendente de TensorFlow.

Clone su repositorio

Descargue una copia de su repositorio remoto username/docs en su máquina local. Este es el directorio de trabajo donde hará los cambios:

git clone [email protected]:<var>username</var>/docs
cd ./docs

Agregue un repositorio ascendente para mantenerlo actualizado (opcional)

Para mantener su repositorio local sincronizado con tensorflow/docs, agregue un repositorio remoto ascendente para descargar los últimos cambios.

Nota: Asegúrese de actualizar su repositorio local antes de iniciar una contribución. Las sincronizaciones periódicas con el canal ascendente reducen la posibilidad de que se produzca un conflicto de fusión cuando envíe su solicitud de extracción.

Agregue un repositorio remoto:

<code class="devsite-terminal">git remote add upstream [email protected]:tensorflow/docs.git</code>

# View remote repos
<code class="devsite-terminal">git remote -v</code>
origin    [email protected]:<var>username</var>/docs.git (fetch)
origin    [email protected]:<var>username</var>/docs.git (push)
upstream  [email protected]:tensorflow/docs.git (fetch)
upstream  [email protected]:tensorflow/docs.git (push)

Para actualizar:

<code class="devsite-terminal">git checkout master</code>
<code class="devsite-terminal">git pull upstream master</code>

<code class="devsite-terminal">git push</code>  # Push changes to your GitHub account (defaults to origin)

Flujo de trabajo de GitHub

1. Cree una nueva rama

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

<code class="devsite-terminal">git checkout -b <var>feature-name</var></code>

<code class="devsite-terminal">git branch</code>  # List local branches
  master
* <var>feature-name</var>

2. Haga cambios

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

Confirme el cambio de su archivo:

# View changes
<code class="devsite-terminal">git status</code>  # See which files have changed
<code class="devsite-terminal">git diff</code>    # See changes within files

<code class="devsite-terminal">git add <var>path/to/file.md</var></code>
<code class="devsite-terminal">git commit -m "Your meaningful commit message for the change."</code>

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

3. Cree una solicitud de extracción

Cargue su rama local en su repositorio remoto de GitHub (github.com/username/docs):

git push

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

4. Revise

Los responsables del mantenimiento y otros contribuyentes revisarán su solicitud de extracción. Participe en el debate y realice los cambios solicitados. Cuando se apruebe su solicitud de extracción, se fusionará en el repositorio de documentos ascendente de TensorFlow.

Éxito: sus cambios han sido aceptados en la documentación 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.

Blocs de notas interactivos

Aunque es posible editar el archivo JSON del bloc de notas con el editor de archivos basado en la web de GitHub, no se recomienda ya que un JSON con errores de formato puede dañar el archivo. Asegúrese de probar el bloc de notas antes de enviar una solicitud de extracción.

Google Colaboratory es un entorno de bloc de notas alojado que facilita la edición (y la ejecución) de la documentación de los blocs de notas. Para cargar los blocs de notas de GitHub en Google Colab, basta con pasar la ruta a la URL de Colab. Por ejemplo, el bloc de notas 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 de Chrome que sustituye la URL cuando se navega por un bloc de notas en GitHub. Esto es útil cuando se abre un bloc de notas en la bifurcación de repositorio, porque los botones superiores siempre enlazan a la rama master de TensorFlow Docs.

Formateo de los blocs de notas

Una herramienta de formateo de blocs de notas hace que los archivos fuente de Jupyter sean consistentes y más fáciles de revisar. Dado que los entornos de creación de blocs de notas difieren en lo que respecta a la salida de archivos, sangría, metadatos y otros campos no especificados, nbfmt usa valores predeterminados opinados con preferencia por el flujo de trabajo de TensorFlow docs Colab. Para dar formato a un bloc de notas, instale las herramientas de bloc de notas 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 documentación de TensorFlow, los blocs de notas sin celdas de salida se ejecutan y prueban; los blocs de notas con celdas de salida guardadas se publican tal cual. nbfmt respeta el estado del bloc de notas y usa la opción --remove_outputs para eliminar explícitamente las celdas de salida.

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

Edición 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 se deben apegar a la guía de estilo de los documentos de TensorFlow .

Descargue archivos de bloc 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 bloc de notas, copie y edite la plantilla de bloc de notas de TensorFlow.

Flujo de trabajo Colab-GitHub

En lugar de descargar un archivo de bloc de notas y usar un flujo de trabajo de Git local, puede editar y actualizar su bifurcación de repositorio de GitHub directamente desde Google Colab:

1. En su repositorio username/docs bifurcado, use la IU web de GitHub para crear una nueva rama.

2. Navegue hasta el archivo del bloc de notas para editarlo.

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 bloc de notas 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 debería vincular el repositorio y la rama correspondientes. 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 responsables del mantenimiento revisan la solicitud de extracción.

Éxito: sus cambios han sido aceptados en la documentación de TensorFlow.

Traducciones

El equipo de TensorFlow trabaja con la comunidad y los proveedores para facilitar traducciones para tensorflow.org. Las traducciones de blocs de notas y otros contenidos técnicos 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 con la mayor exactitud posible. Dicho esto, las traducciones están escritas 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 apropiada para el lector.

El apoyo lingüístico se determina en función de 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, las preferencias del público y otros indicadores. Dado que cada idioma admitido conlleva un costo, los idiomas que no reciben mantenimiento se eliminan. La inclusión de nuevos idiomas se anunciará en el blog de TensorFlow o en Twitter.

Si su idioma de preferencia no tiene soporte, le recomendamos que se encargue de mantener una bifurcación comunitaria para contribuyentes de código abierto. Estos no se publican en tensorflow.org.