این صفحه شامل جزئیات یک پروژه نویسندگی فنی است که برای فصل اسناد گوگل پذیرفته شده است.
خلاصه پروژه
- سازمان متنباز:
- درباره ما
- نویسنده فنی:
- آیانسینه
- نام پروژه:
- مرجع گزینههای خط فرمان در scancode-toolkit و سازماندهی مجدد ساختار مستندات AboutCode در aboutcode.readthedocs.io
- طول پروژه:
- طول استاندارد (۳ ماه)
شرح پروژه
[۱. گزینههای خط فرمان Scancode-Toolkit]
Scancode-Toolkit مجموعهای از گزینههای خط فرمان را برای سفارشیسازی نحوه انجام اسکن، فرمت خروجی و چندین گزینه دیگر مانند افزونههای پس از اسکن ارائه میدهد. این گزینهها در حال حاضر مستندات مناسبی برای توضیح ندارند و فقط از طریق پرچم "--help" یا "-h" در دسترس هستند. هدف این پروژه ایجاد مستندات کاملی است که موارد زیر را توضیح میدهد:
[۱. تمام گزینههای موجود از طریق خط فرمان]
- هدف: فهرستی جامع از تمام گزینههای ممکن از طریق خط فرمان.
- مرور کلی: ابتدا، گزینههای اسکن پیشفرض به همراه مثالی از خروجی مورد بحث قرار میگیرند. یک نمودار/توضیح کوتاه در مورد نحوه انجام اسکن.
از این پس، این رفتار پیشفرض به عنوان مرجعی برای نحوه تغییر اسکن و خروجی توسط سایر گزینهها عمل میکند.
این موارد باید به تفصیل مورد بحث قرار گیرند و شامل اطلاعات زیر خواهند بود که در بخشهای بعدی ذکر شدهاند.
[۲. شروع ساختار نسخهبندی]
- هدف: راهاندازی یک سیستم نسخهبندی برای حفظ صحیح گزینهها/API و تغییرات مستندات بین انتشارهای متقابل.
- مشکل: در حال حاضر مستندات موجود در ویکی و صفحات ReadTheDocs مربوط به نسخههای قدیمیتر هستند و نیاز به بازسازی اساسی دارند.
- مرور کلی: بخشهایی از جعبه ابزار اسکنکد که بهروزرسانی شدهاند/میتوانند در این نسخه بهروزرسانی شوند عبارتند از
- گزینههای خط فرمان
- رابطهای برنامهنویسی کاربردی (API)
- مستندات (در حال شروع) گزینههای خط فرمان و APIها در نسخهها و نسخههای منتشر شده تغییر میکنند و مستندات نیز باید از آنها پیروی کنند، در غیر این صورت سردرگمی زیادی برای کاربران ایجاد خواهد شد. ابزار خط فرمان [ --help ] از قبل برای هرگونه تغییر در گزینهها بهروزرسانی شده است و میتواند برای تکرار نسخهبندی در مستندات استفاده شود.
[۳. نحوه استفاده از این گزینهها در موارد مختلف]
- هدف: این بخش خلاصهای اولیه از چگونگی استفاده از نتایج اسکن scancode-toolkit در موارد مختلف و گزینههای Scancode-Toolkit که چنین عملکردی را ارائه میدهند، ارائه میدهد.
- مرور کلی: این بخش نمونههای مختلفی از سناریوهای کاربردی و گزینههای پیشنهادی در آن سناریوها را ارائه میدهد.
- توجه: این بخش نیاز به کمک قابل توجه مربی در زمینه ارائه اطلاعات و نکات مربوط به موارد استفاده مختلف Scancode-Toolkit دارد.
[۴. این گزینهها چه چیزی را در اسکن و خروجی تغییر میدهند]
- هدف: این بخش خلاصهای اولیه از چگونگی استفاده از نتایج اسکن scancode-toolkit در موارد مختلف و ابزارهای Aboutcode که چنین عملکردی را ارائه میدهند، ارائه میدهد.
- مرور کلی: گزینهها، رفتار نحوه انجام اسکن را تغییر میدهند. یک حالت پیشفرض اولیه در بخش ابتدایی [1. همه گزینههای موجود از طریق خط فرمان] نشان داده خواهد شد و این بخش تغییراتی را که همه گزینهها در این سناریوی پیشفرض ایجاد میکنند، مقایسه میکند.
[5. قالبهای خروجی و مثالهای آنها]
- هدف: این بخش خلاصهای اولیه از چگونگی استفاده از نتایج اسکن scancode-toolkit در موارد مختلف و ابزارهای Aboutcode که چنین عملکردی را ارائه میدهند، ارائه میدهد.
- مرور کلی: ابزار Scancode دارای پرچمهایی برای مشخص کردن قالبهای خروجی مختلف است که نتایج اسکن در آنها تولید میشوند. این قالبها عبارتند از:
این بخش - فرمتهای خروجی را با جزئیات توضیح دهید
- مثالهایی در مورد فرمتهای خروجی ارائه دهید
- پیوندهای دیگری مربوط به قالب خروجی و کاربرد آن ارائه دهید
- نحوه ذخیره نتایج اسکن در فایلهای خروجی. این همچنین به نحوه تولید این فرمتهای مختلف مرتبط است که در [2. مباحث مربوط به توضیح اسکن کد] توضیح داده خواهد شد.
[6. استفاده تجاری از قالبهای خروجی کد اسکن]
- اهداف: توضیح موارد استفاده تجاری از قالبهای خروجی کد اسکن در فهرست ایدههای GSoD، قالبهای خروجی کد اسکن به عنوان یک ایده مرجع ذکر شده است. این بخش نیز همین ایده را پیادهسازی میکند.
- توجه: این بخش نیاز به کمک قابل توجه مربی در زمینه ارائه نظرات و نکات مربوط به موارد استفاده مختلف تجاری از Scancode-Toolkit دارد.
[۷. نحوه استفاده از این خروجیها توسط سایر پروژههای AboutCode برای تجزیه و تحلیل بیشتر]
- هدف: این بخش خلاصهای اولیه از چگونگی استفاده از نتایج اسکن scancode-toolkit در موارد مختلف و ابزارهای Aboutcode که چنین عملکردی را ارائه میدهند، ارائه میدهد.
- مرور کلی پایه:
- Scancode-Workbench این بخش، مصورسازی نتایج با برنامه دسکتاپ و اشارهگرهایی به مستندات scancode-workbench برای پشتیبانی بیشتر در این زمینه را توضیح میدهد. در صورت لزوم، مستندات مورد نیاز را به scancode-workbench اضافه خواهیم کرد.
- دلتاکد چگونه نتایج اسکنکد توسط دلتاکد برای تعیین تفاوتهای سطح فایل بین دو کدبیس گرفته میشود.
[۲. سازماندهی مجدد ساختار مستندات AboutCode]
این بخش شامل مجموعهای از تغییرات در مستندات Aboutcode است.
[۱. سیستم نسخهبندی]
در [1. گزینههای خط فرمان Scancode-Toolkit -> 2. ساختار نسخهبندی اولیه] به موضوع نسخهبندی گزینههای خط فرمان اشاره شده است. همین امر برای سایر بخشهای مستندات نیز که حاوی دستورات/اطلاعات خاص نسخه هستند و در غیر این صورت باعث سردرگمی میشوند، ضروری است.
[۲. تعیین استانداردها و آزمونهای مستندسازی]
مستندات از قبل تستهایی برای spinx-build (ساخت تمام صفحات و بررسی خطاهای نحوی Sphinx در سراسر آن) و بررسی لینک (بررسی تمام لینکها به صفحات وب دیگر از مستندات) با ادغام مداوم از طریق Travis-CI دارد. (توسط من در این درخواست Pull شماره ۱۷ اضافه شده است) اکنون به بررسیهای بیشتری برای linting خاص در reStructured Text و سایر استانداردها نیاز است. این کار را میتوان با restructuredtext-lint انجام داد اما به تحقیقات بیشتری نیاز دارد و به عنوان بخشی از پروژه GSoD من انجام خواهد شد.
[۳. اضافه کردن بخش «شروع به کار»]
این بخش به عنوان بخش شروع برای تازه واردان عمل خواهد کرد و شامل مجموعهای از اساسیترین و مهمترین اسناد برای شروع کار با پروژههای Aboutcode خواهد بود. هر پروژه Aboutcode این بخش را شامل Scancode-Toolkit، Scancode-Workbench، Deltacode و موارد دیگر خواهد داشت.
[۴. تجدید ساختار بر اساس ۴ عملکرد سند]
مستندات موجود به طور صریح در 4 عملکرد سند - آموزشها، نحوه انجام کارها، مرجع و توضیحات - ساختار نیافتهاند. من پیشنهاد میکنم که آنها را بر این اساس ساختار دهید و اطلاعات/توضیحات/اشارهگرهای بیشتری را در صورت لزوم اضافه کنید. این امر در مورد تمام پروژههای AboutCode و مستندات آنها صدق میکند. در زیر دو نمونه از بازسازی مستندات Scancode-Toolkit که من پیشنهاد میکنم و میخواهم در این پروژه ادامه دهم، آورده شده است. تغییرات مشابهی در بقیه مستندات انجام خواهد شد.
[۵. بازسازی صفحه توسعه (Scancode-Toolkit)]
میتوان اطلاعات بیشتری در مورد کد/APIها اضافه کرد تا برای توسعهدهندگان راحتتر باشد. میتوان به بخش [2. بحثهایی در مورد اسکن کد] در بالا لینک داد. این لینک توضیح نحوهی عملکرد اسکن را به کدی که برای انجام اسکن استفاده میکند، مرتبط میکند. از آنجایی که این پوشهها حاوی بخشهای مختلفی از scancode-toolkit هستند، کاربرد هر یک از آنها را میتوان با APIها، همراه با بحث در مورد نحوهی عملکرد scancode، شرح داد.
- [ cluecode : افزونههایی برای اسکن مجوزها، حق نشر، آدرسهای اینترنتی، ایمیلها ]
- [commoncode: کلاسها و توابع کمکی]
- [کد استخراج: استخراج فرمتهای مختلف آرشیو]
- [formatedcode: قالببندی خروجی برای فرمتهای مختلف فایل خروجی]
- [کد مجوز: کد تشخیص مجوز]
- [packagedcode: تجزیه قالبهای مختلف بسته]
- [plugincode: کلاسهایی برای معماری افزونهها]
- [کد خلاصه: خلاصه اسکن مجوزهای شناسایی شده]
- [textcode: تجزیه متن را مدیریت میکند]
- [typecode: تعیین نوع فایل را مدیریت میکند]
- [scancode: رابط خط فرمان و رابط برنامهنویسی کاربردی برای scancode، بخش اصلی]
این زیربخش شامل اطلاعات/APIهای دقیقی در مورد این بخشهای scancode-toolkit در زیربخشهای مربوطه خواهد بود. دستورالعملهای توسعه در صفحه یا بخش دیگری با زیربخشهای کوچکتر وجود خواهد داشت.
[۶. بازسازی صفحه سوالات متداول (Scancode-Toolkit)]
صفحه سوالات متداول در حال حاضر شامل سوالاتی است که میتوان به آنها پاسخ بهتری داد و باید به صورت جداگانه در قالب مستندات «چگونهها»، «آموزشها» و «مرجعها» سازماندهی شوند.
- ScanCode چگونه کار میکند؟ این موضوع در [2. بحثهایی در مورد اسکن کد] ارجاع داده شده است و بخش کاملاً جداگانهای با جزئیات بسیار بیشتر خواهد بود.
- چگونه میتوان قوانین مجوز جدیدی برای تشخیص پیشرفته اضافه کرد؟ این موضوع قبلاً در بخش «بهبود دستورالعملهای موجود» مورد بحث قرار گرفته است، مستندات به آنجا منتقل خواهند شد.
- چگونه میتوان یک قانون تشخیص مجوز جدید اضافه کرد؟ این موضوع میتواند به صورت جداگانه در یک پست «آموزش» دیگر مطرح شود و در مورد آن توضیح بیشتری داده شود.
- چگونه کار با بخش توسعه را شروع کنیم؟ در حال حاضر یک صفحه توسعه جداگانه وجود دارد و اطلاعات آن همپوشانی زیادی با یکدیگر دارند. تغییر ساختار صفحه توسعه قبلاً در بالا مورد بحث قرار گرفته است.
- مراحل برش یک نسخه جدید این بخش میتواند به یک بخش جداگانه با عنوان «نحوه برش یک نسخه جدید» تبدیل شود.
- سوالات متداول بیشتری پیدا کنید که به سوالات عمومی در مورد پروژه پاسخ میدهند و در دستههای «چگونه»/«آموزش» قرار نمیگیرند.