Untuk makmal minggu ini, saya kini mengeluarkan GENEREADME.

cleobnvntra / genereadme

GENEREADME ialah alat baris arahan yang mengambil fail kod sumber dan menjana fail README.md yang menerangkan kod dalam fail dengan menggunakan LLM.

Contrubutions

Sumbangan kepada GENEREADME dialu-alukan! Sila semak CONTRIBUTING.md untuk mendapatkan garis panduan tentang menyediakan persekitaran, cara menjalankan dan menguji alat serta menyerahkan perubahan.

GENEREADME

GENEREADME ialah alat baris perintah yang mengambil fail, memprosesnya dan menjana fail README dengan penjelasan atau dokumentasi kandungan fail. Alat ini menggunakan penyiapan sembang OpenAI untuk menganalisis fail dan menjana kandungan.

Releasing GENEREADME

Penggunaan

Pasang alat dengan menjalankan arahan berikut:

npm i -g genereadme

Salin selepas log masuk

Alat pada masa ini menyokong Groq dan OpenRouter, yang menggunakan Groq secara lalai. Kunci API yang sah untuk pembekal yang sesuai mesti disediakan.

Sediakan kunci API yang sah sama ada dengan mencipta fail .env atau melalui bendera -a atau --api-key apabila menggunakan arahan:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Salin selepas log masuk

Jalankan alat dengan fail sampel sedia ada atau mula menggunakan fail anda sendiri:

…

Lihat di GitHub

Proses

Menerbitkan alat itu sendiri tidak menjadi masalah sama sekali, namun terdapat beberapa langkah tambahan yang perlu saya ambil untuk memastikan keluaran yang betul.

Penyelidikan

Sebelum saya menumpukan pada proses keluaran, saya mengambil sedikit masa untuk menyelidik amalan terbaik dan langkah untuk menerbitkan pakej ke pendaftaran npm. Inilah yang saya pelajari:

1. Bagaimana untuk menerbitkan pakej ke npm
Untuk memahami proses asas, saya merujuk kepada dokumentasi npm rasmi. Panduan ini memberikan gambaran keseluruhan langkah penting, termasuk menyediakan package.json, menjalankan npm publish dan mengurus versi.

2. Menggunakan Versi Semantik
Versi memainkan peranan penting dalam memberi isyarat perubahan kepada pengguna. Saya melihat prinsip-prinsip Versi Semantik, yang menggunakan format MAJOR.MINOR.PATCH untuk menerangkan perubahan pecah, ciri baharu dan pembetulan pepijat. Ini memastikan alat saya mempunyai nombor versi yang bermakna untuk setiap keluaran.

3. Menguruskan .npmignore
Saya menyelidik cara menggunakan fail .npmignore dengan berkesan untuk memastikan pakej npm saya hanya mengandungi fail yang diperlukan untuk pengguna akhir. Dengan membuat fail ini dengan teliti, saya dapat mengecualikan fail khusus pembangunan seperti fail konfigurasi, ujian dan dokumentasi yang tidak diperlukan dalam pakej yang diterbitkan. Ini bukan sahaja mengurangkan saiz pakej tetapi juga menjadikannya lebih profesional dengan memberi tumpuan semata-mata pada perkara yang sebenarnya diperlukan oleh pengguna untuk menjalankan alat tersebut. Mengurus .npmignore dengan betul ialah langkah kritikal dalam menyediakan keluaran yang digilap.

Lepaskan

Selepas melakukan penyelidikan saya, saya menyemak semula sebarang keperluan, sebarang kemungkinan pepijat dan sebarang ujian yang gagal.
Selepas semuanya kelihatan baik kepada saya, saya terus menerbitkan pakej dengan menjalankan:

npm i -g genereadme

Salin selepas log masuk

NOTA: Menjalankan arahan ini memerlukan pengguna untuk log masuk ke akaun npm mereka dengan menjalankan arahan:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Salin selepas log masuk

Menguji

Sekarang saya telah menerbitkan v1.0.0 GENEREADME, sudah tiba masanya untuk meminta beberapa pengguna akhir untuk menguji sama ada pakej itu berfungsi.
Seperti yang dijangkakan, terdapat beberapa pepijat yang berjaya melaluinya. Satu yang tidak menjejaskan prestasi alat dan satu yang sebenarnya memecahkannya.

Pelarasan

Pepijat arahan versi

Pepijat mudah yang ditemui ialah tentang menggunakan arahan genereadme -v. Perintah ini harus mencetak nama alat dan versi semasa. Walau bagaimanapun, cara saya mengekod bahagian ini ialah saya mendapatkan semula nama projek dan versi daripada package.json dalam direktori semasa. Ini bermakna bahawa jika pengguna akhir menjalankan arahan ini, ia akan memaparkan nama dan versi projek MEREKA dan bukannya saya. Jadi ini adalah penyelesaian yang mudah untuk memastikan ia akan sentiasa mendapatkannya daripada projek yang betul.

Pepijat direktori output

Kini yang ini ialah pepijat yang merosakkan alat yang secara teknikalnya berfungsi dalam ujian tempatan saya, tetapi saya terlupa kes ujian yang mudah.
Struktur folder projek hanya memikirkan pembangun dan penyumbang, jadi mempunyai folder output dalam projek dijangka, yang juga saya tolak ke repo utama yang mengandungi sampel hasil output.

Sekarang, saya perlu ingat bahawa ia akan berbeza sedikit untuk pengguna akhir.
Sebelum ini, kod itu ditulis untuk hanya menulis ke output/ direktori tanpa menyemak kewujudannya, dan untuk membuatnya jika tidak. Ini menyebabkan ujian manual bagi pakej yang diterbitkan gagal kerana pengguna akhir tidak mempunyai output/ direktori, alat itu hanya akan gagal dan bukannya membuatnya jika ia tidak wujud.

Selepas penemuan ini, saya fikir agak mudah, bukan?
Sehingga saya cuba menolak perubahan dengan berfikir "Baiklah, itu membetulkannya!" tetapi yang mengejutkan saya, CI saya gagal!

Pesalahnya:

npm i -g genereadme

Salin selepas log masuk

Jadi ini adalah cara saya menyemak dan mencipta output/ direktori. Walau bagaimanapun, dalam ujian hujung ke hujung saya, saya mengejek fs.existsSync() untuk mengembalikan nilai palsu atas sebab ini:

API_KEY=API_KEY

or

genereadme <files> -a API_KEY
genereadme <files> --api-key API_KEY

Salin selepas log masuk

Fungsi ini menyemak fail konfigurasi toml yang menggunakan fs.existsSync(), dan saya tidak mahu menggunakan fail konfigurasi toml untuk ujian hujung ke hujung saya, saya mengejek kaedah ini untuk mengembalikan palsu, yang kini bercanggah dengan pembetulan pepijat yang saya lakukan.

Saya masih belum menguasai ejekan dan mengetahui cara untuk membuat nilai olok-olok yang berbeza untuk kaedah yang sama untuk keadaan yang berbeza. Jadi sehingga saya mengetahui prosedur itu, saya membuat pembetulan sementara untuk memastikan bahawa output/ direktori dialih keluar sebelum setiap kes ujian.