Performans Yardımcı Pilot projesi

Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.

Proje özeti

Açık kaynak kuruluşu:
Performans Ortak Pilot Programı
Teknik yazar:
arzoo14
Projenin adı:
Kitap proje alanları içeriğini, diyagramların iyileştirilmesinin zorlu bir hedefiyle birlikte readthedocs ve reStructuredText biçimine dönüştürün.
Proje süresi:
Standart uzunluk (3 ay)

Proje açıklaması

ÖZET:

Topluluk web sitesi, topluluğun sunduğu teklifler, değerli katkıları, becerileri, dokümanları, eğiticileri vb. hakkındaki düşünceleri yaydığı için açık kaynak bir organizasyonda önemli bir rol oynar. Bu nedenle projem, kitap proje alanlarının içeriğini aktarıp güncelleyerek açık kaynaklı tüm katkıda bulunanlar için kullanılabilirliği ve kolaylığı artırmayı amaçlıyor. Örneğin, docbook içeriği, REST API dokümanları üzerinde barındırılan dokümanlar, REST API belgeleri ve Bu proje, bu içeriği daha kolay değiştirmelerine ve genişletmelerine olanak tanıyarak topluluğa katkıda bulunanların da yararına olacaktır. Zorlayıcı bir hedef olmanın yanı sıra, belgelerdeki diyagramlar, belgelere daha profesyonel bir görünüm kazandırmak için iyileştirilecek.

TEKLİF:

  1. GENEL BAKIŞ: Performans Ortak Pilot dokümanları şu anda birkaç farklı biçimde mevcuttur. Bunlar arasında belge kitabı biçimindeki PCP kitapları, kılavuz biçiminde REST API ve markdown biçimindeki pbench kılavuzları bulunur. Böylece kuruluşun mevcut bakım grubu, mümkün olduğunca bakım gerektirmeyen ve geliştirici topluluğunun içeriğinin sade ve kolay bir şekilde bakımına odaklanmasını sağlayan bir çözüme ihtiyaç duyduklarını tespit etti. Bu yüzden, kurumun mevcut ihtiyaçlarına göre, bu Google Dokümanlar Dönemi’nde aşağıdaki hedefleri uygulayacağım:

    1. Doküman kitabı içeriğini reStructuredText biçimine dönüştürüp readthedocs sitesinde barındırma.
    2. REST API dokümanlarını manpage'den geliştiriciye uygun biçime (ör. reStructuredText biçimine) dönüştürme ve bunu 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. Esneme hedefleri, belgelerde yer alan diyagramları iyileştirmektir.

  2. UYGULAMA: Şu anda Performans Ortak Pilot dokümanları belirli bir biçimde mevcut değildir. Dokümanların içeriğinin değiştirilmesi gerektiğinde, içeriğin kısıtlanmış bir kullanıcı grubu tarafından değiştirilmesi gerekir. Etkin topluluk üyelerinin dokümanların içeriğini değiştirmeleri ve genişletmeleri kolay değildir.

Kuruluşun bu GSoD sırasında reStructuredText biçimi, Read the Docs (RTD) ve Sphinx'i kullanarak bu sınırlamaları aşmasına izin vereceğim.

Dokümanları Okuma (RTD), dokümanlarımızı bizim için geliştirme, sürüm oluşturma ve barındırma işlemlerini otomatikleştirerek yazılım geliştirme sürecini basitleştirir. Sfenks tarafından oluşturulan belgelerin barındırıldığı bir barındırma platformudur. Sfenks'in gücünden yararlanır ve sürüm denetimi, tam metin arama ve başka yararlı özellikler ekler. Git, Mercurial veya Subversion'tan kod ve doküman dosyalarını alır, ardından dokümanlarımızı derleyip barındırır. Koda erişmek için en yaygın olarak kullanılan sistem olduğu için projemizde GitHub'ı kullanacağız.

Başlamak için "Read the Docs" (Dokümanları Oku) hesabı oluşturacağız ve GitHub hesabını bağlayacağız. Ardından, doküman oluşturmak istediğimiz GitHub deposunu seçeceğiz ve bu noktada büyüyü yapacağız.

Belgeleri oku: - Depomuzu klonlar. - Ana şubemizden belgelerimizin HTML, PDF ve ePub sürümlerini oluşturun. - Tam metin aramasına izin vermek için dokümanlarımızı dizine ekleyin. - Depomuzdaki her etiket ve daldan Sürüm nesneleri oluşturarak bunları isteğe bağlı olarak barındırmamıza olanak tanırız. - Kod depomuzda bir webhook'u etkinleştirin, böylece kodu herhangi bir dala aktardığımızda dokümanlarımız yeniden oluşturulur.

Sfenks, teknik belge yazmak için aşağıdakiler dahil olmak üzere birçok harika özelliğe sahip yetkin bir belge oluşturma aracıdır: - Aynı kaynaklardan web sayfaları, yazdırılabilir PDF'ler, e-okuyucular için dokümanlar (ePub) ve daha fazlasını oluşturabilirsiniz. - Doküman yazmak için reStructuredText öğesini kullanabiliriz. - Çapraz referans veren kodlar ve belgelerden oluşan kapsamlı bir sistem. - Söz dizimi vurgulanmış kod örnekleri. - Birinci ve üçüncü taraf uzantılardan oluşan dinamik bir ekosistem.

Dökümanlar biçiminde mevcut olan iki PCP kitabını rst biçimine dönüştürerek işe başlayacağım. Bunun ardından, REST API dokümanlarının man sayfa biçiminden rst biçimine dönüştürülmesi, ardından pbench markdown içeriğini rst biçimine dönüştürüp en sonunda da bunların tamamını readthedocs sitesinde barındıracağım. Zorlayıcı hedefler, belgelerdeki diyagramları iyileştirmek olacaktır.

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ün, yalnızca o bölümün içeriğini içeren ayrı bir birinci dosyası olacaktır. Örneğin, Performans Ortak Pilot Kullanıcı ve Yönetici Kılavuzu kitabında sekiz bölüm vardır. Bu, söz konusu sekiz bölüme karşılık gelen sekiz farklı rst dosyası olacağı anlamına gelir. İlk dosyanın adı, ileride karışıklık olmaması için bölüm adıyla aynı olacaktır. Şekiller, tablolar ve örnek listelerinden oluşan bir liste, üç farklı ilk dosyada yer alır. İlk içerik, şu anda olduğu şekilde tümüyle köprülü olarak sağlanır. Aynı şey REST API belgeleri ve pbench içeriği için de kullanılır. İçerikler 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 vb. tüm gerekli işlemler yapılır.

2.2. İlk hesabın Sfenks ile entegrasyonu:

ReadtheDokümanlar, varsayılan olarak Sphinx ve reStructuredText (rst) öğelerini kullanır. Sfenx, sistemime önceden yüklendiğinden, belgeleri içerecek şekilde projenin içinde bir dizin oluşturarak (Performans Ortak Pilot Belgeleri olarak adlandırılmıştır) başlayacağım: $ cd /path/to/project $ mkdir docs

Ardından burada sfenks-hızlı başlangıç kılavuzu: $ cd docs $ sfenks-hızlı başlangıç kılavuzu

Bu hızlı başlangıç, gerekli yapılandırmanın oluşturulmasını sağlar. Çoğu durumda yalnızca varsayılanları kabul edebiliriz (ancak gerektiğinde yapılandırma dosyasındaki önemli değişiklikleri yapabiliriz). İşlem tamamlandığında, elimizde bir index.rst dosyası, bir conf.py ve bazı başka dosyalar olur. Index.rst’te, Performance Co-Pilot ile ilgili gerekli tüm ayrıntıları ekleyeceğim ve hem kitaplar, REST API belgeleri hem de pbench kılavuzları için başlıklar oluşturacağım. Kullanıcı başlıklardan herhangi birini tıkladığında, söz konusu başlığın altındaki tüm doküman materyalleri açılır.

NOT: Dizin sayfasının tasarımı, mentorların ve topluluk üyelerinin onayına göre belirlenecek, ihtiyaç ve gereksinimlere göre değiştirilecektir.

index.rst, dokümantasyon çıkış dizinimizdeki (genellikle _build/html/index.html) index.html içine yerleştirilir. Sphinx dokümanlarını herkese açık bir depoda topladıktan sonra, dokümanlarımızı içe aktararak Dokümanları Oku özelliğini kullanmaya başlayabiliriz.

Dokümanlarımıza herhangi bir .rst dosyası eklediğimizde, bu dosyaya karşılık gelen üç dosya daha oluşturulur. Bu dosyalardan biri .doctree uzantılı doctrees klasöründe, ikincisi .html uzantılı html klasöründe ve üçüncüsü ise .rst.txt uzantısına sahip html/_sources klasöründedir.

  1. BELGELERİ BARINDIRMA: Dokümanların internette barındırılması iki adımdan oluşur: 1. Dokümanları içe aktarma: İlk olarak Read The Docs hesabını GitHub'a bağlayacağım ve derleme için doküman projemizi içe aktaracağım. 2. Belgeleri oluşturma: İçe aktarma işlemini tamamladıktan sonra birkaç saniye içinde kod herkese açık depomuzdan alınır ve dokümanlar derlenir.

  2. WEB KANALLARI: Dokümanları Oku özelliğinin, dokümanlarda ve sürümlerdeki değişiklikleri algılamak için kullandığı birincil yöntem webhook kullanmaktır. Webhook'lar, GitHub gibi depo sağlayıcımızla yapılandırılır ve depomuzdaki her kaydetme, birleştirme veya diğer değişiklik ile Dokümanları Okuma'ya bildirilir. Bir webhook bildirimi aldığımızda, değişikliğin projemizin etkin bir sürümle ilgili olup olmadığını belirleriz. Etkin bir sürümle ilgiliyse bu sürüm için bir derleme tetiklenir.

Bu şekilde herkes (yöneticiler, mentorlar, topluluğa katkıda bulunanlar) topluluk dokümanlarını değiştirebilir, genişletebilir veya sürdürebilir ve dokümanlara nelerin eklenmesi ya da dokümanlardan nelerin kaldırılması gerektiğiyle ilgilenmek için kısıtlanmış bir kullanıcı grubu gerekmez.

  1. TEMALAR: Temalar, düzenler, tasarımlar ve arama gibi diğer HTML işlevleri, topluluğun ihtiyaçlarına ve yönergelerine göre belirlenir. Topluluk bağ kurma döneminde, tüm bunları topluluk üyeleriyle tartışacağım.
  1. HEDEFİ GENİŞLETME: Zorlu bir hedef olarak, belgelerde yer alan diyagramları iyileştireceğim. Şu anda diyagramlar çoğunlukla basit siyah beyaz çizimlerden oluşmaktadır. Resimlere daha fazla renk, gölgelendirme, ölçekleme, tutarlılık ve genel olarak daha düzgün / profesyonel bir görünüm kazandıracağım.

Bu amaca hizmet etmek içindraw.io'yu (veya mentorun izniyle başka bir aracı) kullanacağım.

Kavram Kanıtı olarak, document.io'nun yardımıyla dokümanlardaki diyagramlardan birini iyileştirdim. Belgeyi şu adreste bulabilirsiniz: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

KAPSAM Belgesi

PCP kitabının küçük bir bölümünü (docbook biçimi) rst biçimine dönüştürdüm ve readthedocs sitesinde barındırdım. Lütfen buraya göz atın.

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

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

ZAMAN ÇİZELGESİ VE YAYINLANABİLİRLİKLER

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

Bu süreyi toplulukla tanıştırmak, belgeleri gözden geçirmek ve sürecin başlarında kötü kararlar almamak için danışmanlarla birçok konuyu görüşerek geçireceğim. Bu süre zarfında temaları, düzenleri, tasarımları ve arama, gezinme çubuğu gibi diğer işlevleri danışmanlarla ve topluluk üyeleriyle tartışacağım. Projenin adı ve üç konunun tümünün barındırılacağı tek bir web sitesi mi yoksa bu üç konuya karşılık gelen üç farklı web sitesi mi olacağına ilişkin karar, toplulukla bağ kurma döneminde görüşülecektir.

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

***14 Eylül 2020'den 20 Eylül 2020'ye kadar [1. HAFTA] Dokümanlar dosyası içeriğinin, Kullanıcı ve Yönetici Kılavuzu kitabının ilk dört bölümü için ilk biçime dönüştürülmesi.

***21 Eylül 2020'den 27 Eylül 2020'ye kadar [2. HAFTA] Dokümanlar dosyası içeriğinin, Kullanıcı ve Yöneticiler Kılavuzu kitabının sonraki dört bölümü için ilk biçime dönüştürülmesi.

***28 Eylül 2020'den 4 Ekim 2020'ye kadar [3. HAFTA] Programcı Kılavuzu kitabının dört bölümü için doküman içeriği ilk biçime dönüştürülmesi.

***5 Ekim 2020'den 11 Ekim 2020'ye kadar [4. HAFTA] - Her iki PCP kitabının Readthedocs sitesinde barındırılması. - REST API dokümanlarının kılavuz sayfasından rst biçimine dönüştürülmesi. Bu süre boyunca ana açılış sayfası ele alınacaktır. - Son üç hafta ve geçerli hafta boyunca (GSoD projemin) blog yayınları.

***12 Ekim 2020'den 18 Ekim 2020'ye kadar [5. HAFTA] Ölçeklenebilir Zaman Serisi dizininin rst biçimine dönüştürülmesi. Ölçeklenebilir Zaman Serisi dizini şunları kapsar: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metric , GET /series/sources , GET /series/samples , GET /series/load

***19 Ekim 2020'den 25 Ekim 2020'ye kadar [6. HAFTA] PMAPI Barındırıcı Hizmetleri dizininin rst biçimine dönüştürülmesi. PMAPI Barındırıcı Hizmetleri 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/metric

***26 Ekim 2020'den 1 Kasım 2020'ye kadar [7. HAFTA] - Son haftalarda herhangi bir şey kaldıysa önce bu konu ele alınır. - REST API belgelerinin, readthedocs sitesinde barındırılması. - Son iki hafta ve geçerli hafta boyunca (GSoD projemin) blog yayınları.

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

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

***16 Kasım 2020'den 22 Kasım 2020'ye kadar [10. HAFTA] - Web sitelerindeki adında yer alan içerikleri aramak için dizin sayfasına arama işlevinin uygulanması. - Zorlayıcı hedeflerin başlangıcı.

***23 Kasım 2020'den 30 Kasım 2020'ye kadar [11. HAFTA] - Dokümanlarda bulunan tüm diyagramlarda iyileştirmeler yapıldı. - Son ve geçerli haftadaki (GSoD projemin) son blogu. - Kod tabanının kodlama standartlarına uygun olup olmadığının kontrol edilmesi. Uygun değilse bunları standartlara göre değiştirin.

PROJE SONUÇLANDIRMA DÖNEMİ [30 Kasım - 5 Aralık 2020 ]

  • Kalemin kapalı kalma süresi. Son gönderim üzerinde çalışıyoruz ve her şeyin yolunda gittiğinden emin olmak.
  • Nihai iş ürünleri olarak da bilinen proje raporlarının gönderilmesi.
  • Projelerin başarı ve mentorlarla olan çalışma deneyimine ilişkin değerlendirmelerin gönderilmesi.