Proyek Uji Coba Bersama

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:
Uji Coba Bersama Performa
Penulis teknis:
arzoo14
Nama proyek:
Konversi konten area project buku ke format readthedocs dan reStructuredText beserta tujuan utama peningkatan diagram.
Durasi proyek:
Durasi standar (3 bulan)

Project description

ABSTRAK:

Situs komunitas berperan penting dalam organisasi open source karena dapat menyebarkan ide tentang penawaran yang diberikan komunitas, kontribusi berharga mereka, keterampilan mereka, dokumentasi mereka, tutorial mereka, dll. Jadi, project saya bertujuan untuk meningkatkan kegunaan dan kemudahan bagi semua kontributor open source dengan mentransfer dan memperbarui konten area project buku, yaitu konten docbook, dokumentasi API modern, dan konten markdown terstruktur di situs REST.Text Proyek ini juga akan menguntungkan kontributor komunitas karena mereka dapat mengubah dan memperluas konten ini dengan lebih mudah. Selain itu, sebagai tujuan tambahan, diagram dalam dokumentasi akan ditingkatkan untuk memberikan tampilan yang lebih profesional.

PROPOSAL:

  1. RINGKASAN: Dokumentasi Co-Pilot Performa saat ini tersedia dalam beberapa format yang berbeda. Termasuk buku PCP dalam format docbook, REST API dalam format halaman manual, dan panduan pbench dalam format markdown. Jadi, grup pengelola organisasi saat ini mengidentifikasi bahwa mereka memerlukan solusi bebas pemeliharaan, dan yang memungkinkan komunitas developer sepenuhnya fokus untuk memelihara kontennya dengan cara yang sederhana dan mudah. Jadi, sesuai dengan kebutuhan organisasi saat ini, saya akan menerapkan tujuan berikut selama Google Season Dokumen ini:

    1. Mengonversi konten docbook ke format reStructuredText dan menghostingnya di situs readthedocs.
    2. Mengonversi dokumentasi REST API dari halaman manual menjadi format yang mudah digunakan oleh developer, yaitu format reStructuredText dan menghostingnya di situs readthedocs.
    3. Mengonversi konten pbench MarkDown ke format reStructuredText dan menghostingnya di situs readthedocs.
    4. Tujuan tambahan adalah untuk memperbaiki diagram yang ada dalam dokumentasi.

  2. IMPLEMENTASI: Saat ini, dokumentasi Performa Uji Coba tidak ada dalam format tertentu. Setiap kali konten dokumentasi perlu diubah, itu perlu diubah oleh sekelompok pengguna yang dibatasi. Tidak mudah bagi anggota komunitas yang aktif untuk mengubah dan memperluas konten dokumentasi.

Saya akan membiarkan organisasi mengatasi batasan ini selama GSoD ini dengan bantuan format reStructuredText, Read the Docs (RTD), dan Sphinx.

Membaca Dokumen (RTD) menyederhanakan dokumentasi software dengan mengotomatiskan pembuatan, pembuatan versi, dan hosting dokumen untuk kita. Ini adalah platform hosting untuk dokumentasi yang dibuat Sphinx. Editor ini memanfaatkan kecanggihan Sphinx dan menambahkan kontrol versi, penelusuran teks lengkap, serta fitur berguna lainnya. Alat ini mengambil kode dan file dokumen dari Git, Mercurial, atau Subversion, lalu mem-build dan menghosting dokumentasi kita. Kita akan menggunakan GitHub di project karena ini adalah sistem yang paling umum digunakan untuk mengakses kode.

Untuk memulai, kita akan membuat akun Baca Dokumen, dan menautkan akun GitHub. Kemudian kita akan memilih repositori GitHub yang ingin kita bangun dokumentasinya, di mana keajaiban itu terjadi.

Membaca Dokumen akan: - Meng-clone repositori kami. - Buat versi HTML, PDF, dan ePub untuk dokumentasi kami dari cabang master kami. - Mengindeks dokumentasi kami untuk memungkinkan penelusuran teks lengkap. - Membuat objek Version dari setiap tag dan cabang di repositori kami, memungkinkan kami untuk menghostingnya juga secara opsional. - Aktifkan webhook di repositori kami, sehingga saat kami mengirim kode ke cabang mana pun, dokumentasi kami akan dibuat ulang.

Sphinx adalah generator dokumentasi otoritatif yang memiliki banyak fitur hebat untuk menulis dokumentasi teknis, termasuk: - Membuat halaman web, PDF yang dapat dicetak, dokumen untuk e-reader (ePub), dan banyak lagi dari sumber yang sama. - Kita dapat menggunakan reStructuredText untuk menulis dokumentasi. - Sistem yang lengkap dari referensi silang kode dan dokumentasi. - Contoh kode yang ditandai sintaksis. - Ekosistem yang dinamis untuk ekstensi pihak pertama dan ketiga.

Saya akan mulai dengan mengonversi dua buku PCP yang hadir dalam format docbook ke format rst, mengikuti konversi dokumentasi REST API dari format man page ke format rst, lalu konversi konten pbench markdown ke format rst dan pada akhirnya, menghosting semua ini di situs readthedocs. Tujuan tambahannya adalah untuk memperbaiki diagram dalam dokumentasi.

2.1. Konversi ke format reStructuredText: Langkah pertama adalah mengonversi konten dokumentasi menjadi format reStructuredText. Setiap bab akan memiliki file rst terpisah, yang akan berisi konten bab tersebut saja. Misalnya, buku Panduan Pengguna dan Administrator Performa Percobaan mencakup delapan bab. Artinya akan ada delapan {i>file<i} pertama berbeda yang sesuai dengan delapan bab tersebut. Nama {i>file<i} pertama akan sama dengan nama bab untuk menghindari kebingungan di masa mendatang. Daftar gambar, tabel, dan daftar contoh akan ada di tiga {i>file<i} pertama yang berbeda. Konten pertama akan ditautkan secara menyeluruh dengan cara yang sama seperti konten saat ini. Hal yang sama akan digunakan untuk dokumentasi REST API dan konten pbench. Semua hal yang diperlukan, seperti tebal, miring, garis bawah, poin-poin, tabel, ukuran font, gaya kode, ukuran gambar, perataan, dll., akan ditangani saat mengonversi konten ke format rst.

2.2. Integrasi pertama dengan Sphinx:

ReadtheDocs menggunakan Sphinx dan reStructuredText (pertama) sebagai default. Karena Sphinx sudah terinstal sebelumnya di sistem, saya akan mulai dengan membuat direktori di dalam project (dinamai sebagai Performance Co-Pilot Documentation) untuk menyimpan dokumen: $ cd /path/to/project $ mkdir docs

Setelah itu, jalankan sphinx-quickstart di sana: $ cd docs $ sphinx-quickstart

Panduan memulai ini akan menjelaskan langkah-langkah pembuatan konfigurasi yang diperlukan; dalam kebanyakan kasus, kita cukup menerima setelan default (tetapi jika diperlukan, kita dapat membuat perubahan penting pada file konfigurasi). Setelah selesai, kita akan memiliki index.rst, conf.py, dan beberapa file lainnya. Di index.rst, saya akan menambahkan semua detail yang diperlukan tentang Performance Co-Pilot dan akan membuat judul untuk buku, dokumentasi REST API, dan panduan pbench. Ketika pengguna mengklik salah satu judul, semua materi dokumentasi di bawah judul tersebut akan terbuka.

CATATAN: Desain halaman indeks akan sesuai dengan persetujuan mentor dan anggota komunitas dan akan diubah sesuai dengan kebutuhan dan persyaratan.

Index.rst akan dibuat menjadi index.html dalam direktori output dokumentasi (biasanya _build/html/index.html). Setelah kita memiliki dokumentasi Sphinx di repositori publik, kita dapat mulai menggunakan Baca Dokumen dengan mengimpor dokumen kita.

Saat menambahkan file .rst dalam dokumentasi, sesuai dengan file tersebut, tiga file lain akan dibuat, satu di folder doctrees dengan ekstensi .doctree, kedua di folder html dengan ekstensi .html, dan yang ketiga di folder html/_sources dengan ekstensi .rst.txt.

  1. HOSTING DOKUMENTASI: Hosting dokumentasi di internet terdiri dari dua langkah: 1. Mengimpor dokumentasi: Sebagai langkah pertama, saya akan menghubungkan akun Read The Docs dengan GitHub dan mengimpor project dokumentasi kita untuk membangun. 2. Membuat dokumentasi: Dalam beberapa detik setelah menyelesaikan proses impor, kode akan otomatis diambil dari repositori publik kami, dan dokumentasi akan dibuat.

  2. WEBHOOKS: Metode utama yang digunakan Membaca Dokumen untuk mendeteksi perubahan pada dokumentasi dan versi adalah melalui penggunaan webhook. Webhook dikonfigurasi dengan penyedia repositori kami, seperti GitHub, dan dengan setiap commit, penggabungan, atau perubahan lain pada repositori kami, opsi Baca Dokumen akan diberi tahu. Saat menerima notifikasi webhook, kami menentukan apakah perubahan tersebut terkait dengan versi aktif untuk project kami, dan jika ya, build akan dipicu untuk versi tersebut.

Dengan cara ini, siapa pun (admin, mentor, kontributor komunitas) dapat mengubah, memperluas, atau mengelola dokumentasi komunitas, dan tidak ada kelompok pengguna tertentu yang dibatasi untuk menangani apa yang harus ditambahkan ke dokumentasi atau apa yang harus dihapus dari dokumentasi.

  1. TEMA: Tema, tata letak, desain, dan fungsi HTML lainnya seperti penelusuran akan disesuaikan dengan kebutuhan dan pedoman komunitas. Selama periode ikatan komunitas, saya akan membahas semua ini dengan anggota komunitas.
  1. SASARAN STRETCH: Sebagai target tambahan, saya akan memperbaiki diagram yang ada dalam dokumentasi. Saat ini, sebagian besar diagramnya adalah gambar hitam-putih sederhana. Saya akan memberikan lebih banyak warna, bayangan, penskalaan, konsistensi, dan tampilan gambar yang umumnya lebih rapi / lebih profesional.

Untuk mencapai tujuan ini, saya akan menggunakan draw.io (atau alat lainnya atas persetujuan mentor).

Sebagai Proof of Concept, saya telah meningkatkan salah satu diagram yang ada dalam dokumentasi dengan bantuan draw.io. Temukan di sini: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

BUKTI KONSEP

Saya telah mengonversi sebagian kecil buku PCP (format docbook) ke dalam format pertama dan menghostingnya di situs readthedocs. Silakan temukan di sini.

Situs - https://pcp-books.readthedocs.io/en/latest/ Kode - https://github.com/arzoo14/PCP_Books_Demo

Saya juga telah mengonfigurasi webhook di repositori kode dengan bantuan yang memungkinkan perubahan yang dibuat pada repositori kode akan tercermin di situs.

LINIMASA DAN PENGIRIMAN

PERIODE BONDING KOMUNITAS [ 17 Agustus - 13 September 2020 ]

Saya akan menghabiskan waktu ini untuk membiasakan diri dengan komunitas, memeriksa dokumentasi, dan mendiskusikan banyak hal dengan para mentor untuk memastikan tidak ada keputusan buruk yang dibuat di awal proses. Saya akan mendiskusikan tema, tata letak, desain, fungsi lain seperti penelusuran, menu navigasi, dll. dengan mentor dan anggota komunitas selama periode ini. Keputusan nama proyek dan apakah akan ada satu situs web untuk menghosting ketiga topik atau tiga situs web berbeda yang sesuai dengan ketiga topik tersebut akan didiskusikan selama periode ikatan komunitas.

PERIODE PENGEMBANGAN DOC [ 14 September - 30 November 2020 ]

***Dari tanggal 14 September 2020 hingga 20 September 2020 [Minggu 1] Konversi konten docbook menjadi format pertama untuk empat bab pertama buku Panduan Pengguna dan Administrator.

***Mulai 21 September 2020 hingga 27 September 2020 [Minggu ke-2] Konversi konten docbook menjadi format pertama untuk empat bab berikutnya dalam buku Panduan Pengguna dan Administrator.

***Dari 28 September 2020 hingga 4 Oktober 2020 [WEEK 3] Konversi konten docbook menjadi format pertama untuk keempat bab dalam Buku Panduan Programmer.

***Dari 5 Oktober 2020 hingga 11 Oktober 2020 [WEEK 4] - Hosting kedua buku PCP di situs readthedocs. - Konversi dokumentasi REST API dari halaman manual ke format pertama. Halaman landing utama akan dibahas selama periode ini. - Blogging (tentang proyek GSoD saya) selama tiga minggu terakhir dan minggu ini.

***Dari 12 Oktober 2020 hingga 18 Oktober 2020 [WEEK 5] Konversi indeks Scalable Time Series ke format rst. Indeks Deret Waktu yang skalabel mencakup hal berikut: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***Dari 19 Oktober 2020 hingga 25 Oktober 2020 [WEEK 6] Konversi indeks PMAPI Host Services ke format rst. Indeks Layanan Host PMAPI mencakup hal berikut: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***Dari 26 Oktober 2020 hingga 1 November 2020 [Minggu 7] - Jika ada hal yang belum diselesaikan dalam minggu-minggu terakhir, hal itu akan kami bahas terlebih dahulu. - Hosting dokumentasi REST API di situs readthedocs. - Blogging (tentang proyek GSoD saya) selama dua minggu terakhir dan minggu ini.

***Dari tanggal 2 November 2020 hingga 8 November 2020 [WEEK 8] Konversi konten markdown menjadi format pertama untuk pbench guide.

***Dari 9 November 2020 hingga 15 November 2020 [WEEK 9] - Dilanjutkan dengan konversi konten markdown ke format pertama untuk pbench guide. - Hosting panduan pbench di situs readthedocs. - Membuat blog (tentang proyek GSoD saya) untuk minggu lalu dan minggu ini.

***Dari 16 November 2020 hingga 22 November 2020 [WEEK 10] - Implementasi fungsi penelusuran di halaman indeks untuk menelusuri konten apa pun dari namanya di situs. - Awal dari target tambahan.

***Dari 23 November 2020 hingga 30 November 2020 [Minggu ke-11] - Peningkatan semua diagram yang ada dalam dokumentasi. - Blog terakhir (proyek GSoD saya) untuk minggu terakhir dan minggu ini. - Memeriksa apakah codebase sesuai standar coding atau tidak. Jika tidak, ubah sesuai standar.

PERIODE FINALIZASI PROYEK [ 30 November - 5 Desember 2020 ]

  • Periode nonaktif pensil. Mengerjakan penyerahan akhir dan memastikan bahwa semuanya baik-baik saja.
  • Penyerahan laporan proyek, juga dikenal sebagai produk kerja akhir.
  • Penyerahan evaluasi keberhasilan proyek dan pengalaman kerja dengan para mentor.