กำลังสร้างสมุดบันทึก Jupyter/Colab

เครื่องมือ nbgenerate จะแปลงเนื้อหาและเทมเพลต HTML และ Markdown ของ DevSite ลงในสมุดบันทึก Jupyter ที่ ทำงานร่วมกับ Colab ได้

ภาพรวม

จากเว็บไซต์ Google Colab ให้ทำดังนี้

สมุดบันทึก Colab ให้คุณรวมโค้ดสั่งการและ Rich Text ไว้ในที่เดียว เอกสาร พร้อมด้วยภาพ,HTML LaTeX และอีกมากมาย

ใน Colab คุณสามารถเขียนและเรียกใช้โค้ด Python จากเว็บเบราว์เซอร์ได้โดยไม่ต้องตั้งค่าหรือติดตั้งเพิ่มเติม เนื้อหามาร์กดาวน์สามารถรวมอยู่ด้วยกันได้ด้วยโค้ด เพื่ออนุญาตให้ใช้ Rich Content ในเอกสารเดียวกัน ซึ่งทำให้ Colab Notebook เป็นโซลูชันยอดนิยมที่ไม่เพียงสำหรับการวิจัยเชิงปริมาณและ แมชชีนเลิร์นนิง แต่ยังใช้สำหรับการสาธิตและทดลองใช้ API และ ดังเช่นที่พบได้ทั่วไปในเอกสารสำหรับนักพัฒนาซอฟต์แวร์

ด้วยเหตุนี้ เนื้อหาที่แชร์ในสมุดบันทึก Colab จึงมักจะทับซ้อนกับเนื้อหา เผยแพร่ในเอกสารสำหรับนักพัฒนาซอฟต์แวร์ของ Google เครื่องมือ nbgenerate จะช่วยให้คุณไม่ต้องซิงค์มาร์กอัป DevSite กับสมุดบันทึก Colab ที่รองรับด้วยตนเอง เครื่องมือนี้จะแปลง HTML และ Markdown ของ DevSite เป็นรูปแบบไฟล์ .ipynb ที่ Colab และใช้กับการใช้งานสมุดบันทึก Jupyter อื่นๆ ซึ่งช่วยให้ใช้เนื้อหาใน DevSite เป็นแหล่งที่มาที่เชื่อถือได้เพียงแหล่งเดียวสำหรับทั้งเอกสารนักพัฒนาซอฟต์แวร์และสมุดบันทึก Colab

คุณสามารถดูรายละเอียดทางเทคนิคและข้อมูลเบื้องต้นได้ในเอกสารการออกแบบต้นฉบับที่ nbgenerate-dd

การใช้งานพื้นฐาน

หากต้องการสร้างสมุดบันทึก Colab สําหรับหน้าเว็บในโปรเจ็กต์ DevSite คุณจะต้อง เพิ่มไฟล์ชื่อ _notebooks.yaml ก่อนเรียกใช้คำสั่ง nbgenerate

การเพิ่ม _notebooks.yaml ลงในโปรเจ็กต์

หากต้องการสร้างสมุดบันทึก Colab จากหน้าในโปรเจ็กต์ DevSite ให้เพิ่มไฟล์ชื่อ _notebooks.yaml ไปยังรูทของโปรเจ็กต์ (ในไดเรกทอรีเดียวกับ _project.yaml) ไฟล์ควรมี 1 รายการสำหรับแต่ละหน้าเว็บที่แชร์ Colab Notebook ฟิลด์ source ของแต่ละรายการต้องมีค่าสัมบูรณ์ เส้นทางภายในกลุ่มผู้ใช้ DevSite ที่จะแปลงเป็นสมุดบันทึก Colab ช่อง target ต้องระบุเส้นทางที่เก็บข้อมูล google3 ที่ระบบจะเขียน Colab Notebook ที่สร้างขึ้น

เช่น

- 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

ตัวอย่างนี้ใช้เส้นทางเป้าหมายที่มิเรอร์ไปยัง GitHub โดยใช้ Copybara สมุดบันทึกที่สร้างขึ้นสามารถเปิดผ่านไฮเปอร์ลิงก์ที่เข้าถึงได้แบบสาธารณะ ดูรายละเอียดเกี่ยวกับวิธีซิงค์เส้นทาง google3 กับ GitHub ได้ที่ copybara ดูตัวอย่างที่เพิ่มลิงก์ไปยังโน้ตบุ๊กที่สร้างใน GitHub ได้ที่ ตัวอย่างวิดเจ็ต

กำลังสร้างสมุดบันทึก

ก่อนเรียกใช้ nbgenerate เป็นครั้งแรก ให้ระบุชื่อแทนใน .bashrc และกับ Shell ปัจจุบันของคุณ:

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

จากนั้นคุณจะเรียกใช้ nbgenerate จากบรรทัดคำสั่งเพื่อสร้างไฟล์ทั้งหมดใหม่ได้ แสดงใน _notebooks.yaml:

nbgenerate googledata/devsite/content/en/PROJECT

ระบุเส้นทางอย่างน้อย 1 เส้นทางเป็นอาร์กิวเมนต์ใน nbgenerate เพื่อจำกัดการประมวลผลเฉพาะ ไฟล์หรือเส้นทางที่ระบุ เช่น

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

เส้นทางไดเรกทอรีจะได้รับการประมวลผลซ้ำๆ ไฟล์ใน _notebooks.yaml ที่ หรือ ด้านล่างไดเรกทอรีที่ระบุจะได้รับการประมวลผล

หากคุณได้รับ "ปฏิเสธสิทธิ์" เมื่อเรียกใช้ nbgenerate โดยใช้รายการข้างต้น แทน คุณสามารถเรียกใช้เครื่องมือด้วยคำสั่งต่อไปนี้

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

การกรองเนื้อหา

ในกรณีที่เนื้อหาบางอย่างควรปรากฏในหน้า DevSite หรือในโน้ตบุ๊กของ Colab ที่สร้างขึ้นเท่านั้น แต่ไม่ควรปรากฏทั้ง 2 รายการ คุณสามารถกรองเนื้อหาโดยใช้ตัวแปร is_ipynb ซึ่งตั้งค่าเป็น True ในระหว่างกระบวนการแปลง nbgenerate เพื่อป้องกันข้อผิดพลาดเมื่อจัดเตรียมและเผยแพร่ไปยัง DevSite ให้เพิ่มข้อมูลต่อไปนี้ไว้ใกล้กับด้านบนของหน้าเว็บที่ต้องรวมเนื้อหาแบบมีการเลือก

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

จากนั้นคุณก็ใช้แท็ก Jinja เพื่อควบคุมว่าเนื้อหาใดจะปรากฏใน Colab, DevSite หรือทั้ง 2 รายการ เช่น

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

ตัวอย่างวิดเจ็ต

เว็บไซต์ต่างๆ มักกำหนดวิดเจ็ต DevSite ของตัวเองสรุปพฤติกรรมทั่วไป ด้านล่างคือตัวอย่างวิดเจ็ตที่ใช้ตัวแปร is_ipynb ซึ่งอาจปรับให้เข้ากับเว็บไซต์ของคุณ

วิดเจ็ตปุ่มของ Colab Notebook

เอกสารสำหรับนักพัฒนาซอฟต์แวร์ Earth Engine ใช้วิดเจ็ตที่กำหนดเองเพื่อแสดงปุ่มเรียกใช้ใน Colab และดูแหล่งที่มาบน GitHub อย่างสม่ำเสมอบนหน้า DevSite ที่ซิงค์กับสมุดบันทึก Colab ใน GitHub

ตัวอย่างวิดเจ็ตส่วน

วิดเจ็ตส่วนตัวอย่าง แสดงตัวอย่างวิธีตั้งค่าส่วนที่เป็นแท็บ สำหรับข้อมูลโค้ดที่แสดงในภาษาโปรแกรมหรือสภาพแวดล้อมหลายภาษา วิดเจ็ตจะดูแลเฉพาะการรวมข้อมูลโค้ด Python ไว้ในสมุดบันทึก Colab ทั้งนี้ ลบมาร์กอัปที่ใช้แสดงส่วนที่เป็นแท็บเมื่อเขียน สมุดบันทึก