Tạo sổ tay Jupyter/Colab

Công cụ nbgenerate chuyển đổi nội dung và mẫu HTML và Markdown của DevSite thành sổ tay Jupyter tương thích với Colab.

OverView

Trên trang web Google Colab:

Sổ tay trên Colab giúp bạn kết hợp mã thực thi và văn bản đa dạng thức trong một tài liệu, cùng với hình ảnh, HTML LaTeX và nhiều công cụ khác.

Trong Colab, bạn có thể viết và thực thi mã Python từ trình duyệt web mà không cần thiết lập hoặc cài đặt thêm. Nội dung Markdown có thể được xen kẽ với các ô mã để cho phép cung cấp nội dung đa dạng thức trong cùng một tài liệu. Điều này khiến cho cuốn ghi chú Colab trở thành một giải pháp phổ biến không chỉ cho nghiên cứu định lượng và học máy, mà còn để minh hoạ và thử nghiệm các API và khái niệm như những khái niệm thường thấy trong tài liệu dành cho nhà phát triển.

Vì lý do này, nội dung được chia sẻ trong sổ tay Colab thường trùng lặp với nội dung được xuất bản trong tài liệu dành cho nhà phát triển của Google. Công cụ nbgenerate giúp bạn không cần phải đồng bộ hoá theo cách thủ công mã đánh dấu DevSite với các sổ tay Colab hỗ trợ. Công cụ chuyển đổi DevSite HTML và Markdown thành định dạng tệp .ipynb mà Colab sử dụng và các cách triển khai sổ tay Jupyter khác. Điều này cho phép sử dụng nội dung DevSite làm nguồn đáng tin cậy duy nhất cho cả tài liệu dành cho nhà phát triển và sổ tay Colab.

Bạn có thể xem thông tin cơ bản và chi tiết kỹ thuật trong tài liệu thiết kế ban đầu tại nbgenerate-dd.

Cách sử dụng cơ bản

Để tạo sổ tay Colab cho các trang trong dự án DevSite, bạn cần thêm một tệp có tên là _notebooks.yaml trước khi gọi lệnh nbgenerate.

Thêm _notebooks.yaml vào dự án

Để tạo sổ tay Colab từ các trang trong dự án DevSite, hãy thêm một tệp có tên _notebooks.yaml vào thư mục gốc của dự án (trong cùng thư mục với thư mục trang web của bạn _project.yaml). Tệp này phải bao gồm một mục nhập cho mỗi trang đang được chia sẻ dưới dạng một sổ tay Colab. Trường source của mỗi mục nhập phải chứa đường dẫn tuyệt đối trong khách hàng DevSite để được chuyển đổi thành sổ tay Colab. Chiến lược phát hành đĩa đơn Trường target phải chỉ định đường dẫn kho google3 nơi Colab được tạo sổ tay sẽ được viết.

Ví dụ:

- 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

Ví dụ này sử dụng các đường dẫn mục tiêu được đồng bộ hoá hai chiều lên GitHub bằng cách sử dụng Copybara. rằng các sổ tay đã tạo có thể được mở qua các siêu liên kết có thể truy cập công khai. Hãy xem copybara để biết thông tin chi tiết về cách đồng bộ hoá các đường dẫn google3 với GitHub. Xem thêm Ví dụ về tiện ích để biết các ví dụ về cách thêm đường liên kết đến sổ tay đã tạo trong GitHub.

Tạo sổ tay

Trước khi chạy nbgenerate lần đầu tiên, hãy xác định một bí danh trong .bashrc và cho shell hiện tại:

alias nbgenerate="/google/bin/releases/devsite/tools/nbgenerate/nbgenerate.par"

Sau đó, bạn có thể chạy nbgenerate từ dòng lệnh để tạo lại tất cả các tệp được liệt kê trong _notebooks.yaml:

nbgenerate googledata/devsite/content/en/PROJECT

Chỉ định một hoặc nhiều đường dẫn làm đối số cho nbgenerate để hạn chế quá trình xử lý đối với các tệp hoặc đường dẫn đã chỉ định, ví dụ:

nbgenerate third_party/devsite/developers/en/earth-engine/guides

Đường dẫn thư mục được xử lý đệ quy; bất kỳ tệp nào trong _notebooks.yaml tại hoặc bên dưới thư mục được chỉ định sẽ được xử lý.

Nếu bạn nhận được thông báo "Quyền bị từ chối" khi chạy nbgenerate bằng cách sử dụng phương thức trên đại diện, bạn cũng có thể chạy công cụ này bằng lệnh sau:

blaze run //devsite/tools/nbgenerate -- googledata/devsite/content/en/PROJECT

Lọc nội dung

Trong trường hợp một số nội dung chỉ nên xuất hiện trong các trang của DevSite hoặc trong đã tạo sổ tay Colab chứ không phải cả hai, bạn có thể lọc nội dung bằng Biến is_ipynb được đặt thành True trong lượt chuyển đổi nbgenerate của chúng tôi. Để tránh lỗi khi tạo bản dựng và phát hành lên DevSite, hãy thêm nội dung sau vào đầu các trang cần đưa nội dung một cách có chọn lọc:

    
{% if is_ipynb is not defined %}{% set is_ipynb=False %}{% endif %}

Sau đó, bạn có thể sử dụng thẻ Jinja để kiểm soát nội dung xuất hiện trong Colab, DevSite hoặc cả hai. Ví dụ:

# 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!');
```

Ví dụ về tiện ích

Các trang web thường xác định các tiện ích DevSite riêng để đóng gói các hành vi phổ biến. Dưới đây là một số ví dụ về các tiện ích sử dụng biến is_ipynb. Biến này có thể được điều chỉnh cho phù hợp với trang web của bạn.

Tiện ích nút sổ tay Colab

Tài liệu dành cho nhà phát triển Earth Engine sử dụng một tiện ích tuỳ chỉnh để hiển thị một cách nhất quán các nút Chạy trong Colab và Xem nguồn trên GitHub trên các trang DevSite được đồng bộ hoá với sổ tay Colab trong GitHub.

Tiện ích mục mẫu

Tiện ích phần mẫu cung cấp ví dụ về cách thiết lập các phần theo thẻ cho các đoạn mã được trình bày bằng nhiều ngôn ngữ hoặc môi trường lập trình. Tiện ích này chỉ đảm nhận việc đưa các đoạn mã Python vào sổ tay Colab. Phương thức này cũng xoá mã đánh dấu dùng để hiển thị các phần có thẻ khi ghi sổ tay.