A ferramenta nbgenerate converte conteúdo e modelos HTML e Markdown do DevSite
em notebooks Jupyter compatíveis com o Colab.
Visão geral
No site do Google Colab:
Com os notebooks do Colab, você pode combinar código executável e rich text em um único documento, além de imagens, HTML, LaTeX e muito mais.
No Colab, o código Python pode ser escrito e executado em um navegador da Web sem nenhuma configuração ou instalação adicional. O conteúdo do Markdown pode ser intercalado com código células para permitir que conteúdo avançado seja fornecido no mesmo documento. Isso torna Os notebooks do Colab são uma solução conhecida não apenas para pesquisa quantitativa e machine learning, mas também para demonstrar e fazer testes com APIs e conceitos como aqueles normalmente encontrados na documentação do desenvolvedor.
Por esse motivo, o conteúdo compartilhado em notebooks do Colab geralmente se sobrepõe ao conteúdo publicado na documentação para desenvolvedores do Google. A ferramenta nbgenerate elimina as precisará sincronizar manualmente a marcação do DevSite com os notebooks do Colab compatíveis. A ferramenta converte o HTML e o Markdown do DevSite para o formato de arquivo .ipynb usado pelo Colab e outras implementações de notebook do Jupyter. Isso permite que o conteúdo do DevSite seja usado como uma única fonte de verdade para documentos de desenvolvedor e notebooks do Colab.
O histórico e os detalhes técnicos podem ser encontrados no documento de design original em nbgenerate-dd.
Uso básico
Para gerar notebooks do Colab para páginas no seu projeto do DevSite, adicione um arquivo chamado _notebooks.yaml antes de invocar o comando nbgenerate.
Como adicionar _notebooks.yaml ao projeto
Para gerar notebooks do Colab a partir de páginas de um projeto do DevSite, adicione um arquivo chamado
_notebooks.yaml para a raiz do projeto, que está no mesmo diretório do arquivo
_project.yaml). O arquivo deve incluir uma entrada para cada página compartilhada
como um bloco do Colab. O campo source de cada entrada precisa conter o valor absoluto
no locatário do DevSite para ser convertido em um bloco do Colab. O campo
target precisa especificar o caminho do depósito google3 em que os notebooks
do Colab gerados serão gravados.
Exemplo:
- 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
Este exemplo usa caminhos de destino espelhados no GitHub usando o Copybara para que os notebooks gerados possam ser abertos por hiperlinks acessíveis publicamente. Consulte o copybara (em inglês). para detalhes sobre como sincronizar os caminhos do Google3 com o GitHub. Consulte também Exemplos de widgets que adicionam links para notebooks gerados no GitHub.
Como gerar notebooks
Antes de executar nbgenerate pela primeira vez, defina um alias no
.bashrc e no shell atual:
alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"
Em seguida, execute nbgenerate na linha de comando para gerar todos os arquivos novamente
listado em _notebooks.yaml:
nbgenerate googledata/devsite/content/en/PROJECT
Especifique um ou mais caminhos como argumentos para nbgenerate para restringir o processamento aos
arquivos ou caminhos especificados, por exemplo:
nbgenerate third_party/devsite/developers/en/earth-engine/guides
Os caminhos de diretório são processados recursivamente. qualquer arquivo em _notebooks.yaml em ou
abaixo do diretório especificado serão processados.
Se você receber a mensagem "Permissão negada" ao executar nbgenerate usando o alias
acima, também poderá executar a ferramenta com o seguinte comando:
blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT
Como filtrar conteúdo
Nos casos em que parte do conteúdo só aparece nas páginas do DevSite ou no notebook do Colab gerado, mas não nos dois, é possível filtrar o conteúdo usando a variável is_ipynb, que é definida como True durante o processo de conversão de nbgenerate. Para evitar erros ao preparar e publicar no DevSite, adicione o
seguinte conteúdo perto da parte de cima das páginas que precisam incluir conteúdo seletivamente:
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}
Em seguida, use as tags Jinja para controlar qual conteúdo aparece no Colab, no DevSite ou em ambos. Exemplo:
# 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!');
```
Exemplos de widget
Os sites frequentemente definem os próprios widgets DevSite para encapsular comportamentos comuns. Confira abaixo alguns exemplos de widgets que usam a variável is_ipynb, que pode ser adaptada ao seu site.
Widget de botões do notebook do Colab
A documentação para desenvolvedores do Earth Engine usa um widget personalizado para mostrar de forma consistente os botões Run in Colab e View source on GitHub nas páginas do DevSite sincronizadas com os notebooks do Colab no GitHub.
Exemplo de widget de seção
O widget de seção de exemplo. fornece um exemplo de como configurar seções com guias para snippets de código apresentados em várias linguagens de programação ou ambientes. O widget só inclui snippets de Python nos notebooks do Colab. Ela também remove a marcação usada para exibir as seções com guias ao escrever o notebook.