Bu sayfada, Google Season of Docs için kabul edilen bir teknik doküman yazma projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- AboutCode
- Teknik yazar:
- ayansinha
- Proje adı:
- scancode-toolkit'teki komut satırı seçenekleri için referans ve aboutcode.readthedocs.io adresindeki AboutCode dokümanlarının yapısını yeniden düzenleme
- Proje uzunluğu:
- Standart süre (3 ay)
Proje açıklaması
[ 1. Scancode-Toolkit Komut Satırı Seçenekleri ]
Scancode-Toolkit, taramanın nasıl yapılacağını, çıkış biçimini ve tarama sonrası eklentiler gibi diğer birçok seçeneği özelleştirmek için çeşitli komut satırı seçenekleri sunar. Bu seçeneklerle ilgili şu anda bunları açıklayan uygun bir doküman bulunmamaktadır ve yalnızca "--help" veya "-h" işaretiyle kullanılabilirler. Bu proje, aşağıdakileri açıklayan eksiksiz bir doküman oluşturmayı amaçlamaktadır:
[ 1. Komut Satırı Aracılığıyla Kullanılabilen Tüm Seçenekler ]
- Amaç: Komut satırı üzerinden kullanılabilen tüm seçeneklerin kapsamlı bir listesini oluşturmak.
- Temel Genel Bakış: İlk olarak, 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.
Bundan sonra bu varsayılan davranış, diğer seçeneklerin taramayı ve çıktıyı nasıl değiştirdiğine dair bir referans olarak kullanılır.
Bunlar ayrıntılı olarak ele alınacak ve sonraki bölümlerde belirtildiği gibi aşağıdaki bilgileri içerecektir.
[ 2. Sürüm Oluşturma Yapısını Başlatma ]
- Amaç: Sürümler arası seçenekleri/API'yi ve doküman değişikliklerini düzgün bir şekilde korumak için sürüm oluşturma sistemini başlatın.
- Sorun: Şu anda wiki'deki ve ReadTheDocs sayfalarındaki dokümanlar eski sürümlere ait ve büyük bir yeniden yapılandırma gerektiriyor.
- Temel Genel Bakış: ScanCode-Toolkit'in güncellenen/güncellenebilecek bölümleri
- Komut Satırı Seçenekleri
- API'ler
- Belgeler (Başlatılacak) Komut satırı seçenekleri ve API'ler sürümlerde ve yayınlarda değiştirilir. Belgelerin de bu değişikliklere uygun olması gerekir. Aksi takdirde kullanıcılar büyük bir kafa karışıklığı yaşar. Komut satırı yardımcı programı [ --help ], seçeneklerdeki tüm değişiklikler için zaten güncellenmiştir ve dokümanlardaki sürüm oluşturmayı kopyalamak için kullanılabilir.
[ 3. Bu Seçenekler Farklı Durumlarda Nasıl Kullanılabilir? ]
- Amaç: Bu bölümde, scancode-toolkit'in tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceği ve bu işlevselliği sağlayan Scancode-Toolkit seçenekleri hakkında temel bir özet sunulacaktır.
- Temel Genel Bakış: Bu bölümde, farklı kullanım alanı senaryoları ve bu senaryolarda önerilen seçenekler hakkında örnekler verilmektedir.
- Not: Bu bölüm, Scancode-Toolkit'in çeşitli kullanım alanlarıyla ilgili girişler ve ipuçları açısından mentordan önemli ölçüde yardım almayı gerektirir.
[ 4. Bu Seçenekler, Tarama ve Çıkışta Neleri Değiştirir?
- Amaç: Bu bölümde, scancode-toolkit'in tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceği ve bu işlevselliği sağlayan Aboutcode araçları hakkında temel bir özet sunulacaktır.
- Temel Genel Bakış: Seçenekler, taramanın nasıl gerçekleştirileceğini değiştirir. Temel bir varsayılan durum, ilk bölümde [ 1. Komut satırında kullanılabilen tüm seçenekler ] ve bu bölüm, tüm seçeneklerin bu varsayılan senaryoda yaptığı değişiklikleri karşılaştırır.
[ 5. Çıkış biçimleri ve örnekleri ]
- Amaç: Bu bölümde, scancode-toolkit'in tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceği ve bu işlevselliği sağlayan Aboutcode araçları hakkında temel bir özet sunulacaktır.
- Temel Bakış: Scancode-Tool, tarama sonuçlarının oluşturulacağı farklı çıkış biçimlerini belirtmek için işaretlere sahiptir. Bunlar:
Bu bölüm, - Çıkış biçimlerini ayrıntılı olarak açıklama
- Çıkış biçimleri hakkında örnekler verin.
- Çıkış biçimine ve kullanımına karşılık gelen diğer bağlantıları verme
- Tarama sonuçlarının çıkış dosyalarında nasıl depolandığı Bu, farklı biçimlerin nasıl oluşturulduğuyla ilgili bilgileri de içerir. Bu konu [ 2. Kod taramayı açıklayan tartışmalar ].
[ 6. Scancode Çıkış Biçimlerinin İşletme Tarafından Kullanımı ]
- Hedefler: Scancode Çıkış Biçimlerinin İş Kullanım Alanlarını Açıklama GSoD fikirleri listesinde, Scancode Çıkış Biçimleri referans fikir olarak belirtilmiştir. Bu bölümde de aynı durum geçerlidir.
- Not: Bu bölüm, Scancode-Toolkit'in çeşitli iş kullanım alanlarıyla ilgili girişler ve ipuçları açısından mentordan önemli ölçüde yardım alınmasını gerektirir.
[ 7. Bu çıktıların, daha fazla analiz için diğer AboutCode projeleri tarafından nasıl kullanıldığı ]
- Amaç: Bu bölümde, scancode-toolkit'in tarama sonuçlarının farklı amaçlarla nasıl kullanılabileceği ve bu işlevselliği sağlayan Aboutcode araçları hakkında temel bir özet sunulacaktır.
- Temel Genel Bakış:
- Scancode-Workbench Bu bölümde, sonuçların masaüstü uygulamasıyla görselleştirilmesi ve aynı konuda daha fazla destek için Scancode-Workbench belgelerine yönelik işaretçiler açıklanmaktadır. Gerekirse gerekli belgeleri scancode-workbench'e ekler.
- Deltacode İki kod tabanı arasındaki dosya düzeyindeki farklılıkları belirlemek için tarama kodu sonuçları Deltacode tarafından nasıl kullanılır?
[ 2. AboutCode Dokümanlarının yapısını yeniden düzenleme ]
Bu bölüm, Aboutcode Dokümanları'nda yapılan bir dizi değişikliği içerir.
[ 1. Sürüm oluşturma sistemi ]
[ 1. Scancode-Toolkit Command Line Options -> 2. Initiate Versioning Structure] the issue of versioning the Command Line options are mentioned. Aynı durum, dokümanların diğer bölümleri için de geçerlidir. Bu bölümlerde, aksi takdirde kafa karışıklığına yol açacak sürüme özgü komutlar/bilgiler yer alır.
[ 2. Belge Standartlarını ve Testlerini Belirleme ]
Dokümanlarda, Travis-CI aracılığıyla sürekli entegrasyonla birlikte spinx-build (tüm sayfaları oluşturur ve baştan sona Sphinx söz dizimi hatalarını kontrol eder) ve bağlantı kontrolü (dokümandaki diğer web sayfalarına giden tüm bağlantıları kontrol eder) için testler zaten mevcuttur. (Added by me in this Pull Request #17 ) Now it needs more checks for specific linting in reStructured Text and other standards. Bu, restructuredtext-lint ile yapılabilir ancak daha fazla araştırma gerektirir ve GSoD projem kapsamında tamamlanacaktır.
[ 3. "Başlarken" bölümü ekleme ]
Bu bölüm, yeni kullanıcılar için başlangıç bölümü olarak işlev görecek ve Aboutcode projelerine başlamak için en temel ve önemli belgelerin bir derlemesini içerecek. Scancode-Toolkit, Scancode-Workbench, Deltacode ve diğerleri dahil olmak üzere her Aboutcode projesinde bu bölüm bulunur.
[ 4. 4 Belge İşlevine Göre Yeniden Yapılandırma ]
Mevcut dokümanlar, 4 doküman işlevi (Eğitimler, Nasıl Yapılır?, Referans ve Açıklamalar) şeklinde açıkça yapılandırılmamıştır. Gerekli bilgileri/açıklamaları/ipuçlarını ekleyerek bunları buna göre yapılandırmayı öneriyorum. Bu, tüm AboutCode projeleri ve belgeleri için geçerlidir. Aşağıda, Scancode-Toolkit belgelerinin yeniden yapılandırılmasıyla ilgili önerdiğim ve bu projede uygulamak istediğim iki örnek verilmiştir. Benzer değişiklikler, dokümanların geri kalanında da yapılacaktır.
[ 5. Geliştirme Sayfasını Yeniden Yapılandırma (Scancode-Toolkit) ]
Kod/API'ler hakkında daha fazla bilgi eklenerek geliştiriciler için daha kolay hale getirilebilir. [ 2. Yukarıdaki [Kod Tarama ] bölümünü açıklayan tartışmalar. Bu, taramanın nasıl çalıştığına dair açıklamayı, taramayı gerçekleştirmek için kullanılan koda bağlar. Bu klasörler, scancode-toolkit'in farklı bölümlerini içerir. Bu nedenle, API'lerle birlikte kullanımları, scancode'un nasıl çalıştığıyla ilgili tartışma bağlamında ayrıntılı olarak açıklanabilir.
- [ cluecode : plugins for scanning licenses, copyrights, urls, emails ]
- [ commoncode : helper classes and functions]
- [ extractcode : extracts different archive formats ]
- [ formattedcode : output formatting for different output file formats ]
- [ 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 : handles file type determinations ]
- [ scancode : CLI and API to scancode, the core part ]
Bu alt bölümde, scancode-toolkit'in bu kısımlarıyla ilgili ayrıntılı bilgiler/API'ler alt alt bölümler halinde yer alacaktır. Geliştirme kuralları, başka bir sayfada veya daha küçük alt bölümler içeren başka bir bölümde yer alır.
[ 6. SSS sayfasını yeniden yapılandırma (Scancode-Toolkit) ]
SSS sayfasında şu anda daha iyi yanıtlanabilecek sorular var ve bunlar ayrı ayrı Nasıl Yapılır? (How To), Eğitici (Tutorial) ve Referans belgeleri olarak yapılandırılmalıdır.
- ScanCode nasıl çalışır? Bu sorun [ 2. Kod Tarama'yı açıklayan tartışmalar ve çok daha ayrıntılı bir şekilde tamamen ayrı bir bölüm olacaktır.
- Gelişmiş algılama için yeni lisans kuralları nasıl eklenir? Bu sorun daha önce "Mevcut Nasıl Yapılır? içeriklerini iyileştirme" bölümünde ele alınmıştı. Dokümanlar oraya taşınacak.
- Yeni lisans algılama kuralı nasıl eklenir? Bu konu ayrı bir "Nasıl Yapılır?" gönderisi olarak ele alınabilir ve daha ayrıntılı bir şekilde açıklanabilir.
- Geliştirmeye nasıl başlanır? Zaten ayrı bir geliştirme sayfası var ve bilgiler büyük ölçüde örtüşüyor. Geliştirme sayfasının yeniden yapılandırılması yukarıda ele alınmıştır.
- Yeni bir sürüm oluşturma adımları Bu, ayrı bir "Yeni bir sürüm oluşturma" makalesine dönüştürülebilir.
- Proje hakkında genel soruları yanıtlayan ve "Nasıl Yapılır?"/"Eğitici" kategorilerine girmeyen diğer SSS sorularını inceleyin.