nbdev

Memulai

nbdev adalah platform pengembangan berbasis notebook. Cukup tulis buku catatan dengan markup ringan dan dapatkan dokumentasi, pengujian, integrasi berkelanjutan, dan pengemasan berkualitas tinggi secara gratis!

nbdev membuat proses debug dan pemfaktoran ulang kode Anda jauh lebih mudah dibandingkan lingkungan pemrograman tradisional karena Anda selalu memiliki objek langsung di ujung jari Anda. nbdev juga mempromosikan praktik terbaik rekayasa perangkat lunak karena pengujian dan dokumentasi adalah yang terbaik.

• Dokumentasi dibuat secara otomatis menggunakan Quarto dan dihosting di Halaman GitHub. Dokumen mendukung LaTeX, dapat dicari, dan secara otomatis diberi hyperlink (termasuk dukungan siap pakai untuk banyak paket melalui nbdev-index )
• Publikasikan paket ke PyPI dan conda serta alat untuk menyederhanakan rilis paket. Praktik terbaik Python diikuti secara otomatis, misalnya, hanya objek yang diekspor yang disertakan dalam __all__
• Sinkronisasi dua arah antara buku catatan dan kode sumber teks biasa memungkinkan Anda menggunakan IDE untuk navigasi kode atau pengeditan cepat
• Pengujian yang ditulis sebagai sel buku catatan biasa dijalankan secara paralel dengan satu perintah
• Integrasi berkelanjutan langsung dengan GitHub Actions yang menjalankan pengujian dan membangun kembali dokumen Anda
• Notebook ramah Git dengan kait Jupyter/Git yang membersihkan metadata yang tidak diinginkan dan membuat konflik penggabungan dalam format yang dapat dibaca manusia
• …dan masih banyak lagi!

Memasang

nbdev berfungsi di macOS, Linux, dan sebagian besar sistem operasi bergaya Unix. Ini berfungsi pada Windows di bawah WSL, tetapi tidak di bawah cmd atau Powershell.

Anda dapat menginstal nbdev dengan pip:

pip install nbdev

… atau dengan conda (atau mamba):

conda install -c fastai nbdev

Perhatikan bahwa nbdev harus diinstal ke lingkungan Python yang sama dengan yang Anda gunakan untuk Jupyter dan proyek Anda.

Cara menggunakan nbdev

Cara terbaik untuk mempelajari cara menggunakan nbdev adalah dengan menyelesaikan panduan tertulis atau panduan video:

Alternatifnya, ada versi singkat panduan video dengan bagian coding yang dipercepat menggunakan pustaka Python unsilence – 27 menit lebih cepat, namun sedikit lebih sulit untuk diikuti.

Anda juga dapat menjalankan nbdev_help dari terminal untuk melihat daftar lengkap perintah yang tersedia:

!n bdev_help 

 nbdev_bump_version        Increment version in settings.ini by one
nbdev_changelog           Create a CHANGELOG.md file from closed and labeled GitHub issues
nbdev_clean               Clean all notebooks in `fname` to avoid merge conflicts
nbdev_conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
nbdev_create_config       Create a config file.
nbdev_docs                Create Quarto docs and README.md
nbdev_export              Export notebooks in `path` to Python modules
nbdev_filter              A notebook filter for Quarto
nbdev_fix                 Create working notebook from conflicted notebook `nbname`
nbdev_help                Show help for all console scripts
nbdev_install             Install Quarto and the current library
nbdev_install_hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
nbdev_install_quarto      Install latest Quarto on macOS or Linux, prints instructions for Windows
nbdev_merge               Git merge driver for notebooks
nbdev_migrate             Convert all markdown and notebook files in `path` from v1 to v2
nbdev_new                 Create an nbdev project.
nbdev_prepare             Export, test, and clean notebooks, and render README if needed
nbdev_preview             Preview docs locally
nbdev_proc_nbs            Process notebooks in `path` for docs rendering
nbdev_pypi                Create and upload Python package to PyPI
nbdev_readme              Create README.md from readme_nb (index.ipynb by default)
nbdev_release_both        Release both conda and PyPI packages
nbdev_release_gh          Calls `nbdev_changelog`, lets you edit the result, then pushes to git and calls `nbdev_release_git`
nbdev_release_git         Tag and create a release in GitHub for the current version
nbdev_requirements        Writes a `requirements.txt` file to `directory` based on settings.ini.
nbdev_sidebar             Create sidebar.yml
nbdev_test                Test in parallel notebooks matching `path`, passing along `flags`
nbdev_trust               Trust notebooks matching `fname`
nbdev_update              Propagate change in modules matching `fname` to notebooks that created them
nbdev_update_license      Allows you to update the license of your project.

Pertanyaan Umum

T: Apa yang dimaksud dengan peringatan “Menemukan sel yang berisi campuran impor dan penghitungan. Silakan gunakan sel terpisah”?

J: Anda tidak boleh memiliki sel yang tidak diekspor, dan berisi campuran pernyataan import bersama dengan kode lainnya. Misalnya, jangan lakukan ini dalam satu sel:

 import some_module
some_module . something ()

Sebaliknya, bagi ini menjadi dua sel, satu yang import some_module , dan yang lainnya melakukan some_module.something() .

Alasannya adalah ketika kami membuat situs web dokumentasi Anda, kami memastikan bahwa semua tanda tangan untuk fungsi yang Anda dokumentasikan adalah yang terbaru, dengan menjalankan fungsi impor, sel yang diekspor, dan show_doc di buku catatan Anda. Saat Anda menggabungkan impor dengan kode lain, kode lain tersebut juga akan dijalankan, yang dapat menyebabkan kesalahan (atau setidaknya perlambatan) saat membuat situs web Anda.

T: Mengapa nbdev meminta akses root? Bagaimana cara menginstal Quarto tanpa akses root?

J: Saat Anda menyiapkan proyek pertama Anda, nbdev akan mencoba mengunduh dan menginstal Quarto secara otomatis untuk Anda. Ini adalah program yang kami gunakan untuk membuat situs dokumentasi Anda.

Proses instalasi standar Quarto memerlukan akses root, dan oleh karena itu nbdev akan meminta kata sandi root Anda selama instalasi. Bagi kebanyakan orang, ini akan berfungsi dengan baik dan semuanya akan ditangani secara otomatis – jika demikian, Anda dapat melewati sisa bagian ini, yang membahas tentang instalasi tanpa akses root.

Jika Anda perlu menginstal Quarto tanpa akses root di Linux, cd terlebih dahulu ke mana pun Anda ingin menyimpannya, lalu unduh Quarto, dan ketik:

dpkg -x quarto * .deb .
mv opt/quarto ./
rmdir opt
mkdir -p ~ /.local/bin
ln -s " $( pwd ) " /quarto/bin/quarto ~ /.local/bin

Untuk menggunakan Quarto versi non-root ini, Anda memerlukan ~/.local/bin dalam variabel lingkungan PATH Anda. (Atau, ubah langkah ln -s untuk menempatkan symlink di tempat lain di jalur Anda.)

T: Seseorang mengatakan kepada saya untuk tidak menggunakan notebook untuk pengembangan perangkat lunak yang “serius”!

J: Tonton video ini. Jangan khawatir, kami masih mendapatkan ini juga, meskipun telah menggunakan nbdev untuk berbagai proyek perangkat lunak “sangat serius” selama tiga tahun terakhir, termasuk perpustakaan pembelajaran mendalam, klien API, ekstensi bahasa Python, antarmuka pengguna terminal, dan banyak lagi !

Berkontribusi

Jika Anda ingin berkontribusi pada nbdev , pastikan untuk meninjau pedoman kontribusi. Proyek ini mematuhi kode etik fastai. Dengan berpartisipasi, Anda diharapkan menjunjung tinggi kode ini. Secara umum, kami berusaha untuk mematuhi praktik terbaik yang diterima secara umum dalam pengembangan perangkat lunak sumber terbuka.

Pastikan Anda telah menginstal nbdev 's git hooks dengan menjalankan nbdev_install_hooks di repositori kloning.

Hak cipta

Hak Cipta © 2019 dan seterusnya fast.ai, Inc. Berlisensi di bawah Lisensi Apache, Versi 2.0 (“Lisensi”); Anda tidak boleh menggunakan file proyek ini kecuali sesuai dengan Lisensi. Salinan Lisensi disediakan dalam file LISENSI di repositori ini.