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:
- Referencia de API : los documentos de referencia de API se generan a partir de cadenas de documentos en el código fuente de TensorFlow .
- Documentación narrativa : son tutoriales , guías y otros escritos que no forman parte del código de TensorFlow. Esta documentación se encuentra en el repositorio de GitHub de tensorflow/docs .
- Traducciones comunitarias : son guías y tutoriales traducidos por la comunidad. Todas las traducciones de la comunidad se encuentran en el repositorio de tensorflow/docs .
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:
- Mire el repositorio de GitHub de tensorflow/docs .
- Siga la etiqueta de documentos en el foro 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 reposgit 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 changesgit status
# See which files have changedgit diff
# See changes within filesgit 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:
- En su repositorio username bifurcado /docs, use la interfaz de usuario web de GitHub para crear una nueva rama .
- Navegue hasta el archivo del cuaderno para editarlo.
- Abra el cuaderno en Google Colab: use el intercambio de URL o la extensión Abrir en Colab Chrome.
- Edite el cuaderno en Colab.
- 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.
- Después de guardar, busque su repositorio o el repositorio de tensorflow/docs , GitHub debería solicitarle que cree una solicitud de extracción.
- 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.