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:
- AboutCode
- Teknik yazar:
- ayansinha
- Projenin adı:
- scancode-toolkit'taki Komut Satırı Seçenekleri için Referans ve aboutcode.readthedocs.io adresindeki AboutCode dokümanının yapısını yeniden düzenleme
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
[ 1. Scancode-Toolkit Komut Satırı Seçenekleri ]
Scancode-Toolkit, tarama işleminin nasıl yapılacağını, çıkış biçimini ve tarama sonrası eklentiler gibi diğer seçenekleri özelleştirmek için birçok Komut Satırı seçeneğine sahiptir. Bu seçenekler şu anda açıklamalı dokümanlara sahip değildir ve yalnızca "--help" veya "-h" işaretiyle kullanılabilir. Bu projenin amacı, aşağıdakileri açıklayan eksiksiz dokümanlar oluşturmaktır:
[ 1. Komut Satırı aracılığıyla kullanılabilen Tüm Seçenekler ]
- Hedef: Komut satırı üzerinden yapılabilecek tüm seçeneklerin kapsamlı bir listesi.
- Temel Genel Bakış: Öncelikle, varsayılan tarama seçenekleri ve çıkış örneği ele alınır. Taramanın nasıl yapıldığına dair kısa bir grafik/açıklama.
Bu varsayılan davranış, diğer seçeneklerin taramayı ve çıktıyı nasıl değiştirdiğine dair referans olarak kullanılır.
Bunlar ayrıntılı olarak tartışılacak olup sonraki bölümlerde belirtildiği gibi aşağıdaki bilgileri içerecektir.
[ 2. Sürüm Oluşturma Yapısını Başlatma ]
- Hedef: Sürümler arası seçenekleri/API ve doküman değişikliklerini düzgün bir şekilde sürdürmek için bir sürüm sistemi başlatın.
- Sorun: Şu anda wiki ve ReadTheDocs sayfalarındaki dokümanlar eski sürümlere yöneliktir ve büyük çaplı bir yeniden yapılandırmaya ihtiyaç duymaktadır.
- Temel Genel Bakış: Taramalı kod araç setinin sürümde güncellenen/güncellenebilen bölümleri şunlardır:
- Komut Satırı Seçenekleri
- API'ler
- Dokümanlar (Başlatılacak) Sürüm ve sürümlerde komut satırı seçenekleri ve API'ler değişir. Dokümanların da buna uyması gerekir. Aksi takdirde kullanıcılar büyük bir kafa karışıklığı yaşar. Komut satırı yardımcı programı [ --help ], seçeneklerdeki değişiklikler için zaten güncellenmiştir ve dokümanlardaki sürümlendirmeyi kopyalamak için kullanılabilir.
[ 3. Bu seçenekler farklı durumlarda nasıl kullanılabilir? ]
- Amaç: Bu bölümde, scancode-toolkit'un tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceğine ve bu tür işlevler sunan Scancode-Toolkit seçeneklerine dair temel bir özet sunulmaktadır.
- Temel Genel Bakış: Bu bölümde, farklı kullanım alanı senaryosu örnekleri ve bu senaryolarda hangi seçeneklerin önerildiği açıklanmaktadır.
- Not: Bu bölümde, Scancode-Toolkit'in çeşitli kullanım alanlarına ilişkin girişler ve ipuçları için mentörden önemli ölçüde yardım alınması gerekir.
[ 4. Bu seçeneklerin tarama ve çıkışta yaptığı değişiklikler ]
- Amaç: Bu bölümde, scancode-toolkit'un tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceğine ve bu tür işlevler sunan Aboutcode araçlarına dair temel bir özet sunulmaktadır.
- Temel Genel Bakış: Seçenekler, taramanın nasıl gerçekleştirileceğini belirler. Baştaki bölümde temel bir varsayılan durum gösterilecektir [ 1. Komut satırı üzerinden kullanılabilen tüm seçenekler ] ve bu bölümde, tüm seçeneklerin bu varsayılan senaryoya getirdiği değişiklikler karşılaştırılır.
[ 5. Çıkış biçimleri ve örnekleri ]
- Amaç: Bu bölümde, scancode-toolkit'un tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceğine ve bu tür işlevler sunan Aboutcode araçlarına dair temel bir özet sunulmaktadır.
- Temel Bakış: Tarama kodu aracı, tarama sonuçlarının oluşturulacağı farklı çıkış biçimlerini belirtmek için işaretlere sahiptir. Bunlar:
Bu bölümde - Çıkış biçimlerini ayrıntılı olarak açıklama
- Çıkış biçimleriyle ilgili örnekler verin.
- Çıkış biçimine ve kullanımına karşılık gelen diğer bağlantıları verin.
- tarama sonuçlarının çıkış dosyalarında nasıl depolandığı. Bu bağlantı, bu farklı biçimlerin nasıl oluşturulduğuna dair [ 2. Kod Tarama'yı açıklayan tartışmalar ].
[ 6. Tarama Kodu Çıkış Biçimlerinin Ticari Kullanımı ]
- Hedefler: Tarama kodu çıkış biçimlerinin iş kullanım alanlarını açıklayın GSoD fikir listesinde, referans fikir olarak Tarama Kodu Çıkış Biçimleri'nden bahsedilmektedir. Bu bölümde de aynı işlem uygulanır.
- Not: Bu bölümde, Scancode-Toolkit'in çeşitli iş kullanım alanlarına ilişkin girişler ve ipuçları konusunda mentordan önemli ölçüde yardım alınması gerekir.
[ 7. Bu çıkışlar, daha fazla analiz için diğer AboutCode projeleri tarafından nasıl kullanılır? ]
- Amaç: Bu bölümde, scancode-toolkit'un tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceğine ve bu tür işlevler sunan Aboutcode araçlarına dair temel bir özet sunulmaktadır.
- Temel Bakış:
- Scancode-Workbench Bu bölümde, daha fazla destek için masaüstü uygulaması ve scancode-workbench dokümanlarına işaret eden sonuçlarla sonuçları görselleştirmek açıklanmaktadır. Gerekirse scancode-workbench'e gerekli dokümanları ekler.
- Deltacode İki kod tabanı arasındaki dosya düzeyindeki farklılıkları belirlemek için Deltacode tarafından tarama kodu sonuçlarının nasıl alındığı.
[ 2. AboutCode dokümanlarının yapısını yeniden düzenleme
Bu bölümde, Aboutcode dokümanlarında yapılan bir dizi değişiklik yer almaktadır.
[ 1. Sürüm oluşturma sistemi ]
[ 1. Scancode-Toolkit Komut Satırı Seçenekleri -> 2. Sürüm Oluşturma Yapısını Başlatma] bölümünde, komut satırı seçeneklerinin sürüm oluşturma sorunundan bahsedilir. Dokümanların, kafa karışıklığına yol açabilecek sürüme özgü komutlar/bilgiler içeren diğer bölümleri için de aynısı geçerlidir.
[ 2. Doküman Standartları ve Testleri Ayarlama ]
Dokümanda halihazırda Travis-CI üzerinden Sürekli Entegrasyon ile döndürme (tüm sayfaları oluşturur ve Sphinx söz dizimi hatalarını kontrol eder) ve bağlantı kontrolü (dokümanlardaki diğer web sayfalarının tüm bağlantılarını kontrol eder) için testler bulunmaktadır. (Bu Pull Request #17\'de benim tarafımdan eklendi) Artık reStructured Text ve diğer standartlarda belirli linting için daha fazla kontrole ihtiyaç var. Bu, restructuredtext-lint ile yapılabilir ancak daha fazla araştırma gerektirir ve GSoD projemin bir parçası olarak yapılacaktır.
[ 3. "Başlarken" Bölümü Ekleme ]
Bu bölüm, yeni başlayanlar için başlangıç bölümü görevi görecek ve Aboutcode projelerine başlamak için en temel ve önemli belgelerin bir derlemesini içerecektir. Scancode-Toolkit, Scancode-Workbench, Deltacode ve diğerleri dahil olmak üzere her Aboutcode projesinde bu bölüm bulunur.
[ 4. 4 Doküman İşlevine Göre Yeniden Yapılandırılıyor ]
Mevcut dokümanlar, Eğitimler, Nasıl Yapılır, Referans ve Açıklamalar olmak üzere 4 doküman işlevinde açıkça yapılandırılmış değil. Gerekli olduğunda daha fazla bilgi/açıklama/ipucu ekleyerek bunları uygun şekilde yapılandırmayı öneriyorum. Bu, tüm AboutCode projeleri ve dokümanları için geçerlidir. Aşağıda, önerdiğim ve bu projede uygulamak istediğim Scancode-Toolkit belgelerinin yeniden yapılandırılmasına dair iki örnek verilmiştir. Benzer değişiklikler, belgelerin geri kalanında da uygulanacaktır.
[ 5. Geliştirme Sayfasını Yeniden Yapılandırması (Scancode-Toolkit) ]
Geliştirici dostu olması için kod/API'ler hakkında daha fazla bilgi eklenebilir. [ 2. Yukarıdaki Kod Tarama bölümünü açıklayan tartışmalar. Bu bağlantı, taramanın nasıl çalıştığıyla ilgili açıklamayı, taramayı gerçekleştirmek için kullandığı koda yönlendirir. Bu klasörlerde, tarama kodu araç setinin farklı bölümleri olması gibi, bunların kişisel kullanımı, tarama kodunun nasıl çalıştığına ilişkin Tartışma ile bağlantılı olarak API'larla ayrıntılı bir şekilde ele alınabilir.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : farklı arşiv biçimlerini ayıklayın ]
- [ formattedcode : farklı çıkış dosyası biçimleri için çıkış biçimlendirmesi ]
- [ licensedcode : licence detection code ]
- [ packagedcode : parsing various package formats ]
- [ plugincode : classes for the plugins architecture ]
- [ summarycode : summarizes scan on detected licenses ]
- [ textcode : handles text parsing ]
- [ typecode : dosya türü belirlemelerini işler ]
- [ scancode : CLI ve API to scancode, the core part ]
Bu alt bölümde, scancode-toolkit'in bu bölümleri hakkında ayrıntılı bilgiler/API'ler alt alt bölümlerde buna göre yer alır. Geliştirme yönergeleri, daha küçük alt bölümler içeren başka bir sayfada veya başka bir bölümde yer alır.
[ 6. SSS sayfasını yeniden yapılandırma (Scancode-Toolkit) ]
Şu anda SSS sayfasında daha iyi yanıtlanabilecek sorular bulunmaktadır ve ayrı ayrı "Nasıl Yapılır?", Eğiticiler ve Referans belgeleri şeklinde yapılandırılması gerekir.
- ScanCode nasıl çalışır? Bu soruna [ 2. Kod Tarama'yı açıklayan tartışmalar ] ve çok daha ayrıntılı bir şekilde tamamen ayrı bir bölüm olacak.
- Gelişmiş Algılama için Yeni Lisans Kuralları Nasıl Eklenir? Bu sorun daha önce Mevcut "Nasıl Yapılır?" Kılavuzunu İyileştirme bölümünde ele alınmıştı. Dokümanlar buraya taşınacak.
- Yeni bir lisans algılama kuralı nasıl eklenir? Bu konu, ayrı bir "Nasıl Yapılır?" makalesinde ayrıntılı olarak ele alınabilir.
- Geliştirmeye nasıl başlayabilirim? Zaten ayrı bir geliştirme sayfası var ve bilgiler oldukça çakışıyor. Geliştirme sayfasının yeniden yapılandırılması yukarıda ele alınmıştır.
- Yeni bir sürüm yayınlama adımları Bu, "Yeni sürüm yayınlama" başlıklı ayrı bir makaleye dönüştürülebilir.
- Projeyle ilgili genel soruları yanıtlayan ve "Nasıl Yapılır?"/"Eğitim" kategorilerine girmeyen daha fazla SSS sorusunu burada bulabilirsiniz.