Δημιουργία σημειωματάριων Jupyter/Colab

Το εργαλείο nbgenerate μετατρέπει περιεχόμενο και πρότυπα DevSite HTML και Markdown σε σημειωματάρια Jupyter συμβατά με Colab.

Επισκόπηση

Από τον ιστότοπο Google Colab :

Τα σημειωματάρια Colab σάς επιτρέπουν να συνδυάζετε εκτελέσιμο κώδικα και εμπλουτισμένο κείμενο σε ένα μόνο έγγραφο, μαζί με εικόνες, HTML, LaTeX και άλλα.

Στο Colab, ο κώδικας Python μπορεί να γραφτεί και να εκτελεστεί από ένα πρόγραμμα περιήγησης ιστού χωρίς πρόσθετη ρύθμιση ή εγκατάσταση. Το περιεχόμενο Markdown μπορεί να παρεμβάλλεται με κελιά κώδικα για να επιτρέπεται η παροχή εμπλουτισμένου περιεχομένου στο ίδιο έγγραφο. Αυτό καθιστά τα σημειωματάρια Colab μια δημοφιλή λύση όχι μόνο για ποσοτική έρευνα και μηχανική μάθηση, αλλά και για επίδειξη και πειραματισμό με API και έννοιες όπως αυτές που συνήθως απαντώνται στην τεκμηρίωση προγραμματιστών.

Για αυτόν τον λόγο, το περιεχόμενο που μοιράζεται σε σημειωματάρια Colab συχνά επικαλύπτεται με περιεχόμενο που δημοσιεύεται στην τεκμηρίωση προγραμματιστών της Google. Το εργαλείο nbgenerate εξαλείφει την ανάγκη για μη αυτόματο συγχρονισμό της σήμανσης DevSite με υποστηρικτικά σημειωματάρια Colab. Το εργαλείο μετατρέπει το DevSite HTML και το Markdown στη μορφή αρχείου .ipynb που χρησιμοποιείται από το Colab και άλλες υλοποιήσεις φορητών υπολογιστών Jupyter. Αυτό επιτρέπει στο περιεχόμενο του DevSite να χρησιμοποιείται ως ενιαία πηγή αλήθειας τόσο για τα έγγραφα προγραμματιστών όσο και για τα σημειωματάρια Colab.

Μπορείτε να βρείτε το ιστορικό και τις τεχνικές λεπτομέρειες στο πρωτότυπο έγγραφο σχεδίασης στο nbgenerate-dd .

Βασική χρήση

Για να δημιουργήσετε σημειωματάρια Colab για σελίδες στο έργο σας στο DevSite, θα χρειαστεί να προσθέσετε ένα αρχείο με το όνομα _notebooks.yaml πριν καλέσετε την εντολή nbgenerate .

Προσθήκη _notebooks.yaml στο έργο σας

Για να δημιουργήσετε σημειωματάρια Colab από σελίδες ενός έργου DevSite, προσθέστε ένα αρχείο που ονομάζεται _notebooks.yaml στη ρίζα του έργου (στον ίδιο κατάλογο με _project.yaml του ιστότοπού σας). Το αρχείο θα πρέπει να περιλαμβάνει μία καταχώρηση για κάθε σελίδα που μοιράζεται ως σημειωματάριο Colab. Το πεδίο source κάθε καταχώρισης πρέπει να περιέχει την απόλυτη διαδρομή εντός του μισθωτή του DevSite που θα μετατραπεί σε σημειωματάριο Colab. Το πεδίο target πρέπει να προσδιορίζει τη διαδρομή αποθήκης google3 όπου θα γραφτούν τα σημειωματάρια Colab που δημιουργούνται.

Για παράδειγμα:

- 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, έτσι ώστε τα σημειωματάρια που δημιουργούνται να μπορούν να ανοίξουν μέσω υπερσυνδέσμων προσβάσιμων από το κοινό. Δείτε το copybara για λεπτομέρειες σχετικά με τον τρόπο συγχρονισμού των διαδρομών google3 με το GitHub. Δείτε επίσης παραδείγματα γραφικών στοιχείων για παραδείγματα που προσθέτουν συνδέσμους σε σημειωματάρια που δημιουργούνται στο GitHub.

Δημιουργία σημειωματάριων

Πριν εκτελέσετε nbgenerate για πρώτη φορά, ορίστε ένα ψευδώνυμο στο .bashrc και στο τρέχον κέλυφός σας:

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

Στη συνέχεια, μπορείτε να εκτελέσετε nbgenerate από τη γραμμή εντολών για να αναδημιουργήσετε όλα τα αρχεία που αναφέρονται στο _notebooks.yaml :

nbgenerate googledata/devsite/content/en/PROJECT

Καθορίστε μία ή περισσότερες διαδρομές ως ορίσματα για 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 που δημιουργείται, αλλά όχι και στα δύο, μπορείτε να φιλτράρετε το περιεχόμενο χρησιμοποιώντας τη μεταβλητή is_ipynb , η οποία ορίζεται σε True κατά τη διαδικασία μετατροπής nbgenerate . Για να αποφύγετε σφάλματα κατά την τοποθέτηση και τη δημοσίευση στο DevSite, προσθέστε τα ακόλουθα κοντά στην κορυφή των σελίδων που πρέπει να περιλαμβάνουν επιλεκτικά περιεχόμενο:

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

Στη συνέχεια, μπορείτε να χρησιμοποιήσετε ετικέτες Jinja για να ελέγξετε ποιο περιεχόμενο εμφανίζεται στο Colab, στο DevSite ή και στα δύο. Για παράδειγμα:

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

Παραδείγματα widget

Οι ιστότοποι συχνά ορίζουν τα δικά τους γραφικά στοιχεία DevSite για να ενσωματώνουν κοινές συμπεριφορές. Ακολουθούν ορισμένα παραδείγματα γραφικών στοιχείων που χρησιμοποιούν τη μεταβλητή is_ipynb , η οποία μπορεί να προσαρμοστεί στον ιστότοπό σας.

Γραφικό στοιχείο κουμπιών σημειωματάριου Colab

Η τεκμηρίωση προγραμματιστή του Earth Engine χρησιμοποιεί ένα προσαρμοσμένο γραφικό στοιχείο για να εμφανίζει με συνέπεια τα κουμπιά Εκτέλεση στο Colab και Προβολή πηγής στα κουμπιά GitHub σε σελίδες DevSite συγχρονισμένα με σημειωματάρια Colab στο GitHub.

Δείγμα γραφικού στοιχείου ενότητας

Το γραφικό στοιχείο δείγματος ενότητας παρέχει ένα παράδειγμα του τρόπου ρύθμισης ενοτήτων με καρτέλες για αποσπάσματα κώδικα που παρουσιάζονται σε πολλές γλώσσες προγραμματισμού ή περιβάλλοντα. Το γραφικό στοιχείο φροντίζει να περιλαμβάνει μόνο αποσπάσματα Python σε σημειωματάρια Colab. Καταργεί επίσης τη σήμανση που χρησιμοποιείται για την εμφάνιση των ενοτήτων με καρτέλες κατά τη σύνταξη του σημειωματάριου.