La herramienta nbgenerate convierte el contenido y las plantillas de HTML y Markdown de DevSite en notebooks de Jupyter compatibles con Colab.
Resumen
Desde el sitio de Google Colab:
Los notebooks de Colab te permiten combinar código ejecutable y texto enriquecido en un único documento, junto con imágenes, HTML, LaTeX y mucho más.
En Colab, el código de Python se puede escribir y ejecutar desde un navegador web sin configuración ni instalación adicionales. El contenido de Markdown se puede intercalar con el código. celdas para permitir que se proporcione contenido enriquecido en el mismo documento. Esto hace que los notebooks de Colab sean una solución popular no solo para la investigación cuantitativa y el aprendizaje automático, sino también para demostrar y experimentar con APIs y conceptos como los que se suelen encontrar en la documentación para desarrolladores.
Por este motivo, el contenido que se comparte en los notebooks de Colab a menudo se superpone con el contenido publicado en la documentación para desarrolladores de Google. La herramienta nbgenerate elimina la es necesario sincronizar manualmente el lenguaje de marcado de DevSite con notebooks de Colab compatibles. La herramienta convierte el HTML y Markdown de DevSite al formato de archivo .ipynb que usan Colab y otras implementaciones de notebooks de Jupyter. Esto permite que el contenido de DevSite se use como una única fuente de información para los documentos para desarrolladores y los notebooks de Colab.
Los antecedentes y los detalles técnicos se pueden encontrar en el documento de diseño original en nbgenerate-dd.
Uso básico
Para generar notebooks de Colab para las páginas de tu proyecto de DevSite, deberás
añadir un archivo llamado _notebooks.yaml antes de invocar el comando nbgenerate.
Agrega _notebooks.yaml a tu proyecto
Para generar notebooks de Colab a partir de páginas en un proyecto de DevSite, agrega un archivo llamado _notebooks.yaml a la raíz del proyecto (en el mismo directorio que el _project.yaml de tu sitio). El archivo debe incluir una entrada para cada página que se comparte como notebook de Colab. El campo source de cada entrada debe contener la ruta de acceso absoluta dentro de tu inquilino de DevSite para que se convierta en un notebook de Colab. El
El campo target debe especificar la ruta de acceso de google3 depot en la que se generó Colab.
se escribirán los {i>notebooks<i}.
Por ejemplo:
- source: /earth-engine/ee-image.html
target: //depot/google3/third_party/earthengine_community/ipynb/ee-image.ipynb
- source: /earth-engine/guides/image_objects.md
target: //depot/google3/third_party/earthengine_community/ipynb/guides/image_objects.ipynb
En este ejemplo, se usan rutas de destino que se duplican en GitHub con Copybara. que los notebooks generados puedan abrirse a través de hipervínculos de acceso público Consulta copybara para obtener detalles sobre cómo sincronizar las rutas de acceso de google3 con GitHub. Consulta también Ejemplos de widgets para ver ejemplos que agregan vínculos a notebooks generados en GitHub.
Generando notebooks
Antes de ejecutar nbgenerate por primera vez, define un alias en tu
.bashrc y a tu shell actual:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Luego, puedes ejecutar nbgenerate desde la línea de comandos para volver a generar todos los archivos que se enumeran en _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Especifica una o más rutas de acceso como argumentos para nbgenerate para restringir el procesamiento a los archivos o rutas de acceso especificados, por ejemplo:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Las rutas de acceso de directorio se procesan de forma recursiva. Se procesarán todos los archivos de _notebooks.yaml en el directorio especificado o debajo de él.
Si recibes el mensaje "Permiso denegado" cuando ejecutas nbgenerate con el alias anterior, también puedes ejecutar la herramienta con el siguiente comando:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Cómo filtrar contenido
Cuando cierto contenido solo debería aparecer en las páginas de DevSite o en
notebook de Colab generado, pero no ambos, puedes filtrar el contenido con el
La variable is_ipynb, que se establece en True durante la conversión nbgenerate
el proceso de administración de recursos. Para evitar errores cuando se publica en DevSite y se habilita por etapas, agrega lo siguiente cerca de la parte superior de las páginas que deben incluir contenido de forma selectiva:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Luego, puedes usar etiquetas de Jinja para controlar el contenido que aparece en Colab, DevSite o ambas. Por ejemplo:
# Overview
This section will show in both the DevSite page and in the Colab notebook as
a text cell.
{% if is_ipynb %}
This content will only appear in Colab notebooks but not on DevSite pages. This
is useful for providing Colab-specific initialization and setup instructions or
code.
{% endif %}
{% if not is_ipynb %}
```js
// This code snippet will only be rendered in DevSite but not in Colab
// notebooks.
console.log('Hello, nbgenerate!');
```
{% endif %}
```py
# This snippet will appear in both DevSite and in the Colab notebook as a code
# cell.
print('Hello, nbgenerate!');
```
Ejemplos de widgets
Los sitios suelen definir sus propios widgets de DevSite para encapsular comportamientos comunes. A continuación, se incluyen algunos ejemplos de widgets que usan la variable is_ipynb, que se pueden adaptar a tu sitio.
Widget de botones del notebook de Colab
La documentación para desarrolladores de Earth Engine usa un widget personalizado para mostrar de forma coherente los botones Run in Colab y View source on GitHub en las páginas de DevSite sincronizadas con notebooks de Colab en GitHub.
Ejemplo de widget de sección
El widget de la sección de muestra proporciona un ejemplo de cómo configurar secciones con pestañas para fragmentos de código presentados en varios lenguajes o entornos de programación. El widget se encarga de incluir solo fragmentos de Python en los notebooks de Colab. También quita el marcado que se usa para mostrar las secciones con pestañas cuando se escribe el notebook.