Visualisasi kode python otomatis. Bagian Empat: Dukungan Dokumentasi

Tautan ke bagian sebelumnya:

• Bagian satu - pengantar, primitif grafis diperlukan untuk membuat representasi grafis dari kode
• Bagian dua - implementasi representasi grafis dari generator kode (dilakukan terutama dengan Python), bahasa markup mikro
• Bagian Tiga - Fitur Grafik Baru

Contoh lingkungan yang mendukung representasi grafis ini ditunjukkan pada gambar di bawah ini.


Lingkungan Dukungan Kode Grafis

Bagian keempat dari artikel ini akan fokus pada mendukung proses dokumentasi.

Di sekitar semak

Mari kita lihat apa yang tersedia untuk pengembang dalam hal bekerja dengan dokumentasi.

Python mendukung jalur dokumentasi untuk modul, kelas, dan fungsi. Ini bagus. Komentar juga terkadang digunakan untuk dokumentasi.

Ada generator dokumentasi seperti doxygen dan sphinx . Ini juga bagus.

Namun, terkadang Anda ingin sedikit lebih. Ada saat-saat ketika deskripsi fungsi atau kelas menjadi terlalu besar dan baris dokumentasi (atau komentar) tidak perlu “membengkak”. Jumlah baris yang tidak dapat dieksekusi mulai menekan jumlah baris yang dapat dieksekusi, yang dapat mempersulit pembacaan karena kode buram. Masalah lain adalah berbagai grafik. Anda tidak dapat memasukkan gambar yang sudah jadi ke dalam teks. Anda hanya dapat memasukkan deskripsi diagram, misalnya, diagram UML Plant , tetapi bahkan dalam kasus ini perlu memberikan rendering, yang sulit dilakukan secara langsung dalam teks program.

Solusi untuk masalah ini sederhana - untuk menyimpan deskripsi panjang dalam file yang terpisah, dan meninggalkan catatan dalam kode bahwa dokumentasi ada di sana. Satu file dapat dirender dengan tepat pada waktu yang tepat. Dan tanda dalam kode sebaiknya interaktif, yaitu, memberikan transisi ke dokumentasi dengan satu klik mouse. Pada prinsipnya, penandaan dalam teks program dapat dianggap lebih luas: itu bisa berupa URL, dan beberapa tempat di file lain dari teks sumber, dan gambar, dan file eksternal dengan dokumentasi.

Mudah membayangkan backlink. Katakanlah dokumentasi menyebutkan kelas dari kode sumber program atau bahkan blok kode tertentu. Untuk kasus ini, alangkah baiknya untuk menyediakan transisi cepat ke bagian kode yang diinginkan.

Kita perlu mempertimbangkan skenario penting lainnya. Misalkan selama pengembangan ada keinginan untuk membuat file dokumentasi eksternal. Sangat diinginkan bahwa pertanyaan organisasi - ke mana harus menyimpan, apa yang harus dihubungi, bagaimana menempatkan tautan ke dokumentasi - dipecahkan secara otomatis mungkin sehingga tidak ada penghalang yang tidak perlu yang dapat menghambat impuls lurus untuk membuat dokumentasi.

Diskusi terpisah layak pertanyaan tentang format file dokumentasi. Baru-baru ini, penurunan harga telah mendapatkan popularitas , meskipun ada kritik terhadapnya (misalnya, di sini ). Say github secara otomatis menampilkan dokumentasi penurunan harga ketika Anda memasuki halaman proyek, yang cukup nyaman. Dalam hal ini, Anda harus mengikuti perjanjian intuitif dan sangat sederhana tentang penamaan dan lokasi file. Alat untuk bekerja dengan penurunan harga juga banyak, jadi format ini adalah kandidat yang baik.

Implementasi dalam IDE Codimension

Seiring dengan teks, IDE Codimension mendukung representasi kode grafis. IDE juga mendukung bahasa markup. Oleh karena itu, tugas menambahkan elemen grafis baru untuk menampilkan tautan ke dokumentasi cukup sederhana.

Untuk memulai, kami merumuskan persyaratan untuk fungsionalitas baru dalam bentuk yang ringkas:

• Mendukung format penurunan harga dengan rendering on-the-fly (lihat dan edit)
• Dalam representasi grafis dari kode, dukung elemen baru untuk dokumentasi menggunakan bahasa marka CML
• Elemen grafik untuk dokumentasi harus berfungsi dalam tiga versi: hanya tautan ke tempat lain; hanya jangkar untuk tautan dari tempat lain; dan tautan dan jangkar
• Tautan dapat berupa URL atau arahkan ke file (mungkin dengan nomor baris atau jangkar) yang dapat ditampilkan oleh IDE
• Dalam dukungan penurunan harga diagram UML Plant
• Mendukung pembuatan cepat file dokumentasi baru dan tautan ke mereka untuk presentasi kode secara grafis
• Pertahankan titik awal dokumentasi dokumentasi untuk suatu proyek, mirip dengan bagaimana github melakukannya

Penurunan harga dan rendering

Codimension IDE menggunakan qutepart sebagai komponen editor teks, dan qutepart, pada gilirannya, mendukung penurunan harga di luar kotak: penyorotan sintaks telah dilakukan. Untuk rendering otomatis, Anda dapat menggunakan pendekatan yang sama seperti untuk file python. Bidang utama dibagi menjadi dua bagian. Di sebelah kiri adalah teks penurunan harga, dan di sebelah kanan menampilkan:


Mengedit penurunan harga dengan render otomatis

Rendering, tentu saja, dilakukan secara otomatis. IDE menentukan jeda dalam mengedit teks dan memperbarui rendering jika perlu. Untuk tampilan penurunan harga, sisi kiri dengan editor teks ditekan.

Itu nyaman untuk menggunakan pustaka kabut untuk rendering , yang memungkinkan Anda untuk dengan cepat mengkonversi teks ke HTML. HTML Siap dikirim ke komponen QT untuk ditampilkan. Perpustakaan mistune juga terbukti cukup fleksibel untuk menambah pengakuan pada deskripsi diagram plantUML. Diagram ditambahkan sebagai blok kode dengan bahasa yang sesuai, misalnya:


Pengenalan diagram PlantUML

plantUML mendukung berbagai jenis diagram. Untuk Codimension, deskripsi diagram transparan, yaitu, tidak dianalisis, tetapi plantUML ditransmisikan. Dengan demikian, semua tipe yang didukung akan ditampilkan di viewport. Pada saat penulisan, plantUML mendukung tag awal / akhir berikut untuk berbagai jenis diagram:

• @startuml / @enduml
• @startgantt / @endgantt
• @startsalt / @endsalt
• @startmindmap / @endmindmap
• @startwbs / @endwbs
• @startditaa / @endditaa
• @startjcckit / @endjcckit

File penurunan harga yang dapat diedit dapat berisi beberapa diagram, serta gambar yang diunduh dari jaringan. Situasi yang sering terjadi adalah ketika sangat sedikit teks berubah, dan sumber daya grafis tetap tidak berubah. Agar tidak memompa hal yang sama setiap kali dan tidak membuat ulang diagram, perlu untuk menerapkan cache sumber daya yang sama.

Dari perpustakaan QT, komponen QTextBrowser yang mendukung HTML digunakan. Sayangnya, dialek HTML yang didukung terbatas, sehingga hasil akhirnya hampir tidak mungkin dibuat sempurna. Mungkin cacat ini bisa diperbaiki di masa depan.

Intervensi juga diperlukan oleh pemrosesan klik mouse pada tautan. Beberapa hal berikut mungkin muncul di tautan:

• sumber daya eksternal (dimulai dengan http: // atau dengan https: //)
• file dengan jalur relatif dari root proyek atau dari file saat ini (nyaman ketika direktori proyek dipindahkan di sekitar sistem file)
• file c jalur absolut

Dan jika itu adalah file, maka Anda dapat menentukan (elemen opsional) baik pengidentifikasi jangkar dalam file ini, atau nomor baris. Dalam kedua kasus, informasi tambahan digunakan untuk menggulir file ke lokasi yang diinginkan.

Elemen grafis

Masuk akal untuk memasukkan elemen grafis menggunakan komentar CML baru, mirip dengan yang telah dilakukan, misalnya, untuk grup. CML mendukung atribut, yang juga diperlukan untuk elemen grafis baru.

# cml 1 doc .... 

Tautan ke dokumentasi dalam beberapa hal mirip dengan komentar - ini bukan baris yang dapat dieksekusi dari program, tetapi memberikan informasi tambahan tentang beberapa konteks. Codimension IDE mengenali beberapa jenis komentar: independen, terkemuka, dan lateral. Untuk dokumentasi, tampaknya bijaksana untuk mempertahankan elemen grafik yang independen dan terkemuka dengan cara yang sama seperti untuk komentar. Ada kebingungan dengan elemen samping untuk dokumentasi. Intinya adalah bagaimana komentar samping diberikan untuk blok kode multi-line. Sebuah persegi panjang digambar di sebelah kanan blok, yang mencakup semua garis komentar samping dengan dukungan untuk nomor garis yang cocok. Dan apa yang harus dilakukan jika CML doc bertemu di tengah-tengah komentar pihak tidak sepenuhnya jelas. Di sisi lain, tautan masih mengarah ke tempat lain, sehingga dukungan untuk dokumen CML sisi tampak berlebihan - konteks garis tertentu di blok kode sangat sempit. Dukungan untuk dokumen CML sisi untuk fungsi dan kelas juga tampaknya berlebihan. Oleh karena itu, pada tahap ini hanya dokumen CML yang independen dan terkemuka yang akan dilaksanakan. Perlu dicatat bahwa jika di masa depan ada kebutuhan yang wajar untuk mendukung dokumen CML lateral dan ide yang baik bagaimana menampilkannya, maka fungsi ini dapat ditambahkan.

Mari kita bahas apa yang perlu ditampilkan dalam elemen grafis. Jelas, Anda membutuhkan teks untuk elemen tersebut. Teks diatur oleh pengembang dan memberi tahu Anda apa yang ditunjukkan tautan. Telah disebutkan sebelumnya bahwa diinginkan untuk menyediakan transisi ke dokumentasi dengan satu klik. Teks elemen grafis tidak cocok, karena kontinuitas antara perilaku elemen lain harus dihormati - dengan mengklik mouse, elemen grafis dipilih. Namun, menyelesaikan masalah itu sederhana: Anda dapat menambahkan ikon, misalnya, di sebelah kiri teks, dan mengklik ikon itu akan mengarah ke transisi.

Sekarang daftar atribut untuk komentar doc CML jelas:

• tautan - tautan ke tempat lain
• anchor - anchor identifier untuk tautan dari tempat lain
• judul - teks untuk ditampilkan dalam elemen grafik
• bg, fg, border - warna individual elemen, jika perlu disorot dengan cara khusus

Setidaknya satu dari dua atribut tautan dan jangkar harus ada. Tanpa mereka, komentar doc CML seperti itu tidak masuk akal. Atribut lainnya bersifat opsional. Teksnya mungkin tidak sama sekali, dan warnanya mungkin standar.

Berikut adalah contoh kode menggunakan CML doc dan representasi grafisnya:


Komentar dokumen CML yang independen dan terkemuka

Perbedaan antara elemen pengarah dan elemen independen hanya terjadi jika konektor mengarah: baik ke blok tertentu, atau ke konektor di antara blok.

Ketika kursor mouse berada di atas ikon, dan elemen memiliki atribut tautan, bentuk kursor berubah, menunjukkan bahwa klik akan dilakukan.

Elemen grafis juga mendukung menu konteks. Opsi tersedia untuk melihat atau mengedit atribut elemen, termasuk warna, dan opsi untuk menghapus elemen.

Elemen grafis lainnya

Hampir semua elemen lain dalam representasi grafis dari kode dapat memiliki dokumentasi (pengecualian, misalnya, adalah komentar dan dokumen). Oleh karena itu, mereka memiliki cara untuk membuat item dokumentasi melalui menu konteks.


Menu konteks untuk bekerja dengan dokumentasi

Hanya ada dua opsi. "Tambah / edit tautan tautan / jangkar ..." mengarah ke dialog modal untuk memasukkan atribut tautan, jangkar, dan judul secara manual. Di sini, pengembang memiliki kebebasan penuh untuk mengirim tautan, ke mana harus meletakkan file, dll.

Opsi kedua lebih menarik. Nama item itu panjang, karena tindakan yang dilakukan: "Buat file doc, tambahkan tautan, dan buka untuk diedit". Semua tindakan dilakukan secara otomatis tanpa masukan apa pun, yang memungkinkan Anda untuk menyelesaikan masalah organisasi dengan cepat:

• Keputusan dibuat tentang file di mana dokumentasi akan ditempatkan (kami akan mempertimbangkan di bawah)
• Dalam teks sumber, tambahkan # cml 1 doc ... , yang menunjuk ke file dokumentasi dan memiliki jangkar dan teks yang dihasilkan. Anchor dihasilkan sebagai doc <angka acak>. Teks tetap: Lihat dokumentasi
• Jika file dokumentasi sudah ada, itu terbuka untuk diedit di tab baru
• Jika file dokumentasi tidak ada, file itu dibuat, dibuka untuk diedit di tab baru, dan bantuan singkat ditambahkan ke buffer pengeditan, termasuk cara merujuk ke komentar yang baru saja dimasukkan # cml 1 doc ... komentar.

Keputusan tentang file tergantung pada apakah proyek dimuat. Jika dimuat, maka subdirektori doc dibuat di root proyek dan kemudian jalur relatif dari root proyek ke file teks sumber. Nama file dibentuk dengan mengganti ekstensi dengan .md. Misalnya, jika sebuah proyek terletak di

 /home/me/myProject 

dan dokumentasi ditambahkan untuk file proyek

 /home/me/myProject/src/utils.py 

file dokumentasi akan dibuat

 /home/me/myProject/doc/src/utils.md 

Dengan demikian, struktur dokumentasi untuk kode sumber mengulangi struktur kode sumber, dan bahkan melihat sekilas pada subdirektori dokumen dalam proyek akan cukup untuk navigasi intuitif. Skema ini tampaknya masuk akal untuk perilaku default, yang membantu mempercepat pekerjaan dengan dokumentasi.

Jika proyek tidak dimuat, maka subdirektori doc dibuat di sebelah file, dan di dalamnya file dengan ekstensi yang diubah menjadi .md. Namun, skenario seperti itu tampaknya tidak mungkin. Jika kita berbicara tentang dokumentasi, itu hampir pasti merupakan pekerjaan pada proyek, dan bukan pada file yang terpisah.

Tentu saja, kapan saja Anda dapat mengubah elemen yang dihasilkan secara otomatis baik dengan mengedit # cml 1 doc ... dalam editor teks atau dalam dialog pada representasi grafis.

Titik awal dokumentasi proyek

Mengapa saya memerlukan titik awal dokumentasi? Menurut pendapat saya, itu dapat memfasilitasi proses memasuki proyek bagi mereka yang pertama kali membukanya. Misalnya, dalam hal memperluas komposisi tim pengembangan, atau untuk pengguna proyek. Bayangkan proyek tersebut memiliki dokumentasi dan terdiri dari sejumlah besar file. Di mana untuk memulai? Bagaimana dokumentasi disusun? Daripada berspekulasi dan kemudian memeriksanya, akan lebih mudah untuk memiliki indikasi eksplisit dari titik masuk yang direkomendasikan.

Di sini Anda dapat sedikit memperluas pendekatan github sehingga opsi organisasi dokumentasi default dan spesifik bekerja. Jika tidak ada yang dikatakan, maka kita akan mencari file README.md di root proyek. Dan properti proyek dapat diperluas dengan bidang lain, yang menunjukkan file spesifik dari titik awal dokumentasi.

Ada dua opsi untuk membuka dokumentasi proyek. Sebuah tombol dengan ikon penurunan harga telah ditambahkan ke bilah alat dari jendela utama IDE. Ketika diklik, file dokumentasi akan dibuka dalam mode tampilan, jika tersedia. Jika tidak ada file, maka lokasi file dokumentasi akan ditawarkan dan tab baru akan terbuka dalam mode edit dengan teks - tulisan rintisan. Opsi kedua adalah tautan ke halaman selamat datang Codimension , yang ditampilkan ketika tidak ada tab terbuka lainnya. Teks yang menyertainya akan menyertakan kata-kata tentang dokumentasi proyek dan tautan jika dokumentasi ditemukan. Halaman sambutan inilah yang akan dilihat oleh pengguna yang membuka proyek untuk pertama kali.

Pengujian dalam praktik

Fungsi yang dijelaskan di atas diuji pada kucing, yaitu, pada proyek IDE Codimension itu sendiri . Sekarang paket instalasi termasuk dokumentasi yang disiapkan dalam format penurunan harga. Pengujian fungsi ini tidak dapat dianggap sepenuhnya lengkap, karena dokumentasi disiapkan untuk pengguna akhir, dan bukan oleh kode. Namun, kesan keseluruhan yang ternyata cukup bisa diterima.

Pertanyaan terbuka

Apakah saya memerlukan dukungan untuk elemen sisi CML doc? Jika ya, lalu cara menggambar mereka, misalnya, untuk kasus seperti itu:

 a = 10 # Comment line 1 b = 20 # cml 1 doc title="my side doc" c = 30 # cml+ link="http://codimension.org" d = 40 # Comment line 4 # Comment line 5 

Orang bisa mengenali deskripsi diagram plantUML langsung di baris dokumentasi. Jika dukungan tersebut dilakukan, lalu bagaimana cara menampilkan diagram ini pada representasi grafis dari kode?

Untuk memfasilitasi pembangunan diagram plantUML, orang dapat menambahkan fungsionalitas dengan skenario ini:

• Pengguna mengklik kanan pada kelas dalam representasi grafik dari kode atau di jendela lain (daftar kelas proyek, konten file terstruktur)
• Di menu konteks, pilih item untuk menghasilkan deskripsi kelas dalam format plantUML
• Deskripsi yang dihasilkan disimpan dalam buffer teks.
• Pengguna memasukkan teks ke dalam dokumen penurunan harga dan memodifikasinya jika perlu

Vitalitas skenario semacam itu dipertanyakan, meskipun sepele untuk mengimplementasikannya.

Jika Anda punya ide, silakan bagikan di komentar.