Performans Yardımcı Pilot projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
Performans Yardımcı Pilotu
Teknik yazar:
arzoo14
Proje adı:
Kitap projesi alanlarındaki içeriği, diyagramların iyileştirilmesiyle ilgili ek hedefin yanı sıra readthedocs ve reStructuredText biçimine dönüştürün.
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

ÖZET:

Topluluk web sitesi, topluluğun sunduğu tekliflerin fikrini, değerli katkılarını, becerilerini, dokümanlarını, eğitimlerini vb. yaydığı için açık kaynak kuruluşlarda önemli bir rol oynar.Bu nedenle projem, kitap projesi alanlarındaki içeriği (ör. docbook içeriği, REST API dokümanları ve pbench markdown içeriği) modern, topluluk odaklı readthedocs.io sitesinde barındırılabilmesi için reStructuredText biçimine aktarıp güncelleyerek tüm açık kaynak katkıda bulunanların kullanılabilirliğini ve kolaylığını artırmayı amaçlayacaktır. Bu proje, topluluk üyelerinin bu içeriği daha kolay değiştirmesine ve genişletmesine olanak tanıyarak onlara da fayda sağlayacak. Ayrıca, ek hedef olarak dokümanlar içindeki şemalar daha profesyonel bir görünüme sahip olacak şekilde iyileştirilecek.

PROPOSAL:

  1. GENEL BAKIŞ: Performans Yardımcı Pilot dokümanları şu anda birkaç farklı biçimde mevcuttur. Bunlar arasında docbook biçiminde PCP kitapları, man sayfası biçiminde REST API ve markdown biçiminde pbench kılavuzları yer alır. Bu nedenle kurumun mevcut idareci grubu, mümkün olduğunca bakım gerektirmeyen ve bu çözüm, geliştirici topluluğunun tamamen içeriklerini sade ve kolay bir şekilde korumaya odaklanmasına olanak tanıyan bir çözüme ihtiyaç duyduğunu belirledi. Bu nedenle, kuruluşun mevcut ihtiyaçlarına göre bu Google Dokümanlar Sezonu'nda aşağıdaki hedefleri uygulayacağım:

    1. Docbook içeriğini reStructuredText biçimine dönüştürüp readthedocs sitesinde barındırma
    2. REST API dokümanlarını, kullanım kılavuzundan geliştirici dostu biçime (ör. reStructuredText biçimi) dönüştürüp readthedocs sitesinde barındırma
    3. pbench Markdown içeriğini reStructuredText biçimine dönüştürüp readthedocs sitesinde barındırma
    4. Ulaşılması zor hedefler arasında dokümanlardaki şemaları iyileştirmek yer alır.

  2. UYGULAMA: Performans Yardımcı Pilot dokümanları şu anda belirli bir biçimde mevcut değildir. Dokümanların içeriğinin değiştirilmesi gerektiğinde bu işlem, kısıtlanmış bir kullanıcı grubu tarafından yapılmalıdır. Etkin topluluk üyelerinin doküman içeriğini değiştirmesi ve genişletmesi o kadar kolay değildir.

reStructuredText biçimi, Read the Docs (RTD) ve Sphinx'in yardımıyla kuruluşun bu GSoD sırasında bu sınırlamaları aşmasına yardımcı olacağım.

Read the Docs (RTD), dokümanlarımızı oluşturma, sürümlendirme ve barındırma işlemlerini otomatikleştirerek yazılım dokümanlarını basitleştirir. Sphinx tarafından oluşturulan dokümanlar için bir barındırma platformudur. Sphinx'in gücünü alır ve sürüm denetimi, tam metin arama ve başka kullanışlı özellikler ekler. Git, Mercurial veya Subversion'dan kod ve doküman dosyalarını indirir, ardından dokümanlarımızı oluşturup barındırır. Kodlara erişmek için en yaygın olarak kullanılan sistem olduğu için projemizde GitHub'ı kullanacağız.

Başlamak için bir Read the Docs hesabı oluşturacağız ve GitHub hesabını bağlayacağız. Ardından, belgeleri oluşturmak istediğimiz GitHub deposunu seçeceğiz. İşte bu noktada büyülü olacak.

Read the Docs: - Depomuzu klonlar. - Ana dalımızdan dokümanlarımızın HTML, PDF ve ePub sürümlerini oluşturun. - Tam metin aramaya izin vermek için dokümanlarımızı dizine ekleyin. - Depomuzdaki her etiket ve daldan Version nesneleri oluşturarak bunları isteğe bağlı olarak barındırabiliyoruz. - Depomuzda bir webhook etkinleştirin. Böylece, herhangi bir dala kod aktardığımızda dokümanlarımız yeniden oluşturulur.

Sphinx, teknik dokümanlar yazmak için birçok harika özelliğe sahip, güvenilir bir doküman oluşturucudur. Örneğin: - Aynı kaynaklardan web sayfaları, yazdırılabilir PDF'ler, e-okuyucular için dokümanlar (ePub) ve daha fazlasını oluşturun. - Doküman yazmak için reStructuredText'i kullanabiliriz. - Kod ve dokümanlar için kapsamlı bir çapraz referans sistemi. - Söz dizimi vurgulanan kod örnekleri. - Birinci ve üçüncü taraf uzantılardan oluşan canlı bir ekosistem.

Docbook biçiminde bulunan iki PCP kitabını rst biçimine dönüştürerek başlayacağım. Ardından, REST API dokümantasyonunu man sayfası biçiminden rst biçimine, ardından pbench markdown içeriğini rst biçimine dönüştüreceğim ve sonunda bunların hepsini readthedocs sitesinde barındıracağım. Ulaşılması zor hedefler ise dokümanlar içindeki şemaları iyileştirmektir.

2.1. reStructuredText biçimine dönüştürme: İlk adım, doküman içeriğini reStructuredText biçimine dönüştürmektir. Her bölüm için yalnızca ilgili bölümün içeriğini içeren ayrı bir rst dosyası oluşturulur. Örneğin, Performans Yardımcı Pilot Kullanıcı ve Yönetici Kılavuzu kitabı sekiz bölümden oluşur. Bu, bu sekiz bölüme karşılık gelen sekiz farklı rst dosyası olacağı anlamına gelir. Gelecekte karışıklık olmaması için rst dosyasının adı, bölüm adıyla aynı olur. Üç farklı rst dosyasında şekillerin, tabloların ve örnek listelerinin listesi yer alır. İlk içerik, şu anda mevcut olduğu şekilde tamamen köprü bağlantısı içerecek. REST API dokümanları ve pbench içeriği için de aynı yöntem kullanılacak. İçerik rst biçimine dönüştürülürken kalın, italik, altı çizili, madde işaretleri, tablolar, yazı tipi boyutu, kod stili, resim boyutu, hizalama gibi gerekli tüm işlemler yapılır.

2.2. rst'nin Sphinx ile entegrasyonu:

ReadtheDokümanlar varsayılan olarak Sphinx ve reStructuredText (rst) kullanır. Sphinx sistemime önceden yüklenmiş olduğu için, dokümanları barındıracak bir dizin (Performans Yardımcı Pilotu Dokümanları olarak adlandırılır) oluşturarak başlayacağım: $ cd /path/to/project $ mkdir docs

Ardından, bu dizinde sphinx-quickstart'ı çalıştırın: $ cd docs $ sphinx-quickstart

Bu hızlı başlangıç kılavuzu, gerekli yapılandırmayı oluşturma konusunda size yol gösterecektir. Çoğu durumda, yalnızca varsayılan ayarları kabul edebiliriz (ancak gerektiğinde yapılandırma dosyasında temel değişiklikleri yapabiliriz). İşlem tamamlandığında bir index.rst, conf.py ve başka bazı dosyalar elde ederiz. index.rst dosyasına Performans Yardımcı Pilot ile ilgili gerekli tüm ayrıntıları ekleyeceğim ve hem kitaplar, REST API dokümanları hem de pbench kılavuzları için başlıklar oluşturacağım. Kullanıcı başlıklardan birini tıkladığında o başlığın altındaki tüm doküman malzemeleri açılır.

NOT: Dizin sayfasının tasarımı, mentorların ve topluluk üyelerinin rızalarına göre belirlenir ve ihtiyaçlara ve şartlara göre değiştirilir.

index.rst, doküman çıkış dizinimizdeki (genellikle _build/html/index.html) index.html dosyasına yerleştirilir. Sphinx dokümanlarını herkese açık bir depoda yayınladıktan sonra dokümanlarımızı içe aktararak Read the Docs'u kullanmaya başlayabiliriz.

Belgelerimize bir .rst dosyası eklediğimizde, bu dosyaya karşılık gelen üç dosya daha oluşturulur. Bunlardan biri .doctree uzantılı doctrees klasöründe, ikincisi .html uzantılı Html klasöründe ve üçüncüsü .rst.txt uzantılı html/_sources klasöründe yer alır.

  1. DOĞRULAMAYI BARINDIRMA: Dokümanların internette barındırılması iki adımdan oluşur: 1. Dokümanları içe aktarma: İlk adım olarak Read The Docs hesabını GitHub'a bağlayacağım ve doküman projemizi derleyip içe aktaracağım. 2. Belge oluşturma: İçe aktarma işlemi tamamlandıktan sonra birkaç saniye içinde kod, herkese açık depomuzdan otomatik olarak getirilir ve belgeler derlenir.

  2. WEB KAMERASI: Dokümanlar'ı Okuma, dokümanlarda ve sürümlerde yapılan değişiklikleri tespit etmek için kullanılan birincil yöntem webhook'ların kullanılmasıdır. Webhook'lar, GitHub gibi depo sağlayıcımızla yapılandırılır ve depomuzda yapılan her bir gönderim, birleştirme veya başka bir değişiklikle ilgili olarak Read the Docs bilgilendirilir. Bir webhook bildirimi aldığımızda, değişikliğin projemizin etkin bir sürümüyle ilişkili olup olmadığını belirleriz. İlişkiliyse söz konusu sürüm için bir derleme tetiklenir.

Bu sayede, herkes (yöneticiler, mentorlar, topluluk katılımcıları) topluluk dokümanlarını değiştirebilir, genişletebilir veya yönetebilir. Ayrıca, dokümanlara nelerin ekleneceği veya dokümanlar üzerinden nelerin kaldırılacağı konusunda belirli bir kısıtlanmış kullanıcı grubuna ihtiyaç duyulmaz.

  1. TEMALAR: Temalar, düzenler, tasarımlar ve arama gibi diğer HTML işlevleri, topluluk ihtiyaçlarına ve yönergelerine uygun olacaktır. Toplulukla kaynaşma döneminde tüm bunları topluluk üyeleriyle tartışacağım.
  1. İLERİ HEDEF: İleri hedef olarak, dokümanlar bölümündeki şemaları iyileştireceğim. Şu anda diyagramlar çoğunlukla basit siyah beyaz çizimler şeklindedir. Resimlere daha fazla renk, gölgelendirme, ölçeklendirme, tutarlılık ve genel olarak daha düzenli / daha profesyonel bir görünüm kazandıracağım.

Bu amaç doğrultusunda draw.io'yu (veya mentörlerin izniyle başka bir aracı) kullanacağım.

Kavram Kanıtı olarak, belgelerdeki diyagramlardan birinidraw.io'nun yardımıyla geliştirdim. Lütfen buradan inceleyin: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

KAVRAM TANITIMI

PCP kitabının küçük bir bölümünü (docbook biçimi) rst biçimine dönüştürüp readthedocs sitesinde barındırdım. Buradan ulaşabilirsiniz.

Web sitesi - https://pcp-books.readthedocs.io/en/bilgiler/Kod - https://github.com/arzoo14/PCP_Books_Demo

Ayrıca kod deposunda webhook'ları da yapılandırdım. Bu sayede, kod deposunda yapılan değişiklikler web sitesine de yansıtılır.

ZAMAN TABLOSU VE TESLİM EDİLECEKLER

TOPLULUK BAĞLAMA DÖNEMİ [ 17 Ağustos - 13 Eylül 2020 ]

Bu süreyi toplulukla tanışmak, dokümanları incelemek ve sürecin başında kötü kararlar alınmadığından emin olmak için mentorlarla birçok konuyu tartışmak için kullanacağım. Bu süre zarfında temaları, düzenleri, tasarımları, arama, gezinme çubuğu gibi diğer işlevleri mentorlarla ve topluluk üyeleriyle tartışacağım. Projenin adı ve üç konunun da yer alacağı tek bir web sitesi mi yoksa üç konuya karşılık gelen üç farklı web sitesi mi oluşturulacağı, topluluk bağları oluşturma döneminde ele alınacaktır.

BELGE GELİŞTİRME DÖNEMİ [14 Eylül - 30 Kasım 2020 ]

***14 Eylül 2020 - 20 Eylül 2020 [1. HAFTA] Kullanıcılar ve Yöneticiler Kılavuzu'nun ilk dört bölümü için doküman kitabı içeriğinin ilk biçime dönüştürülmesi.

***21 Eylül 2020 - 27 Eylül 2020 [2. HAFTA] Kullanıcı ve Yönetici Kılavuzu'nun sonraki dört bölümü için doküman kitabı içeriğinin ilk biçime dönüştürülmesi.

***28 Eylül 2020 - 4 Ekim 2020 [3. HAFTA] Programcı Kılavuzu kitabının dört bölümünün tamamı için doküman kitabı içeriğinin rst biçimine dönüştürülmesi.

***5 Ekim 2020 - 11 Ekim 2020 [4. HAFTA] - Her iki PCP kitabının da readthedocs sitesinde barındırılması. - REST API dokümanlarının man sayfasından rst biçimine dönüştürülmesi. Bu süre zarfında ana açılış sayfası da kapsama alınacaktır. - Son üç hafta ve içinde bulunulan hafta için (GSoD projemden) blog yayınlamak.

***12 Ekim 2020 - 18 Ekim 2020 [5. HAFTA] Ölçeklenebilir Zaman Serisi dizininin ilk biçime dönüştürülmesi. Ölçeklenebilir zaman serisi dizini aşağıdakileri kapsar: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***19 Ekim 2020 - 25 Ekim 2020 [6. HAFTA] PMAPI ana makine hizmetleri dizininin rst biçimine dönüştürülmesi. PMAPI Host Services dizini şunları kapsar: 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

***26 Ekim 2020 - 1 Kasım 2020 [7. HAFTA] - Öncelikle, önceki haftalarda kalan konular ele alınacaktır. - REST API dokümanlarının readthedocs sitesinde barındırılması. - Son iki haftada ve içinde bulunulan hafta boyunca (GSoD projemden) blog yayınlamak.

***2 Kasım 2020 - 8 Kasım 2020 [8. HAFTA] pbench kılavuzları için markdown içeriğinin rst biçimine dönüştürülmesi.

***9 Kasım 2020 - 15 Kasım 2020 [9. HAFTA] - Pbench kılavuzları için markdown içeriğinin rst biçimine dönüştürülmesine devam edildi. - Pbench kılavuzlarının Readthedocs sitesinde barındırılması. - Geçen hafta ve geçerli hafta için (GSoD projemden) blog yazma.

***16 Kasım 2020 - 22 Kasım 2020 [10. HAFTA] - Dizin sayfasında, web sitelerindeki içerikleri adlarına göre aramak için arama işlevinin uygulanması. - Zorlayıcı hedeflerin başlangıcı.

***23 Kasım 2020 - 30 Kasım 2020 [11. HAFTA] - Dokümanlardaki tüm diyagramlarda iyileştirme. - Son ve bu hafta için (GSoD projemin) son blog yayını. - Kod tabanının kodlama standartlarına uygun olup olmadığını kontrol etme. Aksi takdirde, bunları standartlara uygun hale getirin.

PROJE FİNALİZASYON DÖNEMİ [30 Kasım - 5 Aralık 2020 ]

  • Kalem kapalı kalma süresi. Son gönderim üzerinde çalışıyoruz ve her şeyin yolunda olduğundan emin oluyoruz.
  • Nihai çalışma ürünleri olarak da bilinen proje raporlarının gönderilmesi.
  • Projelerin başarısı ve mentorlarla çalışma deneyimi hakkındaki değerlendirmelerin gönderilmesi.