این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- درباره کد
- نویسنده فنی:
- ayansinha
- نام پروژه:
- مرجع گزینه های خط فرمان در scancode-toolkit و سازماندهی مجدد ساختار اسناد AboutCode در aboutcode.readthedocs.io
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
[ 1. گزینه های خط فرمان Scancode-Toolkit ]
Scancode-Toolkit دارای مجموعه ای از گزینه های Command Line برای سفارشی کردن نحوه انجام اسکن، فرمت خروجی و چندین گزینه دیگر مانند افزونه های پس از اسکن است. این گزینه ها در حال حاضر مستندات مناسبی برای توضیح آنها ندارند و فقط از طریق پرچم "--help" یا "-h" در دسترس هستند. هدف این پروژه تهیه مستندات کامل است که توضیح می دهد:
[1. تمام گزینه های موجود از طریق خط فرمان]
- هدف: فهرستی جامع از تمام گزینه های ممکن از طریق خط فرمان.
- نمای کلی اولیه: ابتدا، گزینه های اسکن پیش فرض با مثالی از خروجی مورد بحث قرار می گیرد. یک تصویر/توضیح کوتاه در مورد نحوه انجام اسکن.
از این پس، این رفتار پیش‌فرض به عنوان مرجعی عمل می‌کند که چگونه گزینه‌های دیگر اسکن و خروجی را تغییر می‌دهند.
اینها باید به تفصیل مورد بحث قرار گیرند و حاوی اطلاعات زیر هستند همانطور که در بخش های بعدی ذکر شد.
[ 2. راه اندازی ساختار نسخه ]
- هدف: راه‌اندازی یک سیستم نسخه‌سازی برای حفظ صحیح گزینه‌های انتشار متقابل/API و تغییرات اسناد.
- مشکل: در حال حاضر اسناد موجود در ویکی و صفحات ReadTheDocs برای نسخه های قدیمی تر هستند و نیاز به بازسازی اساسی دارند.
- نمای کلی: بخش‌هایی از Scancode-Toolkit که به‌روزرسانی شده‌اند/می‌توانند در نسخه به‌روزرسانی شوند:
- گزینه های خط فرمان
- API ها
- اسناد (برای شروع) گزینه‌های خط فرمان و APIها در نسخه‌ها و نسخه‌ها تغییر می‌کنند و مستندات نیز باید دنبال شوند، در غیر این صورت سردرگمی عظیمی برای کاربران ایجاد می‌کند. ابزار خط فرمان [ --help ] در حال حاضر برای هرگونه تغییر در گزینه ها به روز شده است و می تواند برای تکرار نسخه سازی در اسناد استفاده شود.
[ 3. چگونه می توان از این گزینه ها در موارد مختلف استفاده کرد]
- هدف: این بخش خلاصه‌ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و گزینه‌های Scancode-Toolkit که چنین عملکردی را ارائه می‌دهند، ارائه می‌کند.
- نمای کلی پایه: این بخش نمونه‌های مختلف سناریوهای مورد استفاده و گزینه‌هایی را که در آن سناریوها توصیه می‌شوند، ارائه می‌دهد.
- توجه: این بخش از نظر ورودی ها و اشاره به موارد استفاده مختلف از Scancode-Toolkit به کمک قابل توجهی از مربی نیاز دارد.
[ 4. آنچه که این گزینه ها در اسکن و خروجی تغییر می دهند ]
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی اولیه: گزینه ها رفتار نحوه انجام اسکن را تغییر می دهند. یک مورد پیش‌فرض اولیه در بخش اصلی [1. همه گزینه‌های موجود از طریق خط فرمان] نشان داده می‌شود و این بخش تغییراتی را که همه گزینه‌ها در این سناریوی پیش‌فرض ایجاد می‌کنند مقایسه می‌کند.
[ 5. فرمت های خروجی و نمونه های آنها ]
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی اولیه: Scancode-Tool دارای پرچم هایی برای تعیین فرمت های خروجی مختلف است که در آنها نتایج اسکن تولید می شود. اینها هستند -
این قسمت خواهد شد - فرمت های خروجی را با جزئیات توضیح دهید
- در فرمت های خروجی مثال بزنید
- پیوندهای دیگر مربوط به فرمت خروجی و استفاده از آن را ارائه دهید
- نحوه ذخیره نتایج اسکن در فایل های خروجی این همچنین به نحوه تولید این فرمت‌های مختلف پیوند می‌دهد که در [2. بحث‌هایی که اسکن کد را توضیح می‌دهند] توضیح داده خواهد شد.
[6. استفاده تجاری از فرمت‌های خروجی اسکن کد]
- اهداف: موارد استفاده تجاری فرمت‌های خروجی Scancode را توضیح دهید در فهرست ایده‌های GSoD، فرمت‌های خروجی Scancode به عنوان یک ایده مرجع ذکر شده است. این بخش نیز همین کار را انجام می دهد.
- توجه: این بخش از نظر ورودی ها و اشاره به موارد مختلف استفاده تجاری از Scancode-Toolkit به کمک قابل توجهی از مربی نیاز دارد.
[ 7. نحوه استفاده از این خروجی ها توسط سایر پروژه های AboutCode برای تجزیه و تحلیل بیشتر ]
- هدف: این بخش خلاصه ای اساسی از نحوه استفاده از نتایج اسکن scancode-toolkit در علل مختلف و ابزار Aboutcode که چنین عملکردی را ارائه می دهند، ارائه می دهد.
- نمای کلی:
- Scancode-Workbench این بخش تجسم نتایج را با برنامه دسکتاپ و اشاره گرها به اسناد scancode-workbench برای پشتیبانی بیشتر در مورد آن توضیح می دهد. در صورت لزوم، اسناد مورد نیاز را به scancode-workbench اضافه می کند.
- Deltacode چگونه نتایج اسکن کد توسط Deltacode برای تعیین تفاوت سطح فایل بین دو پایگاه کد گرفته می شود.
[ 2. سازماندهی مجدد ساختار مستندات AboutCode ]
این بخش شامل مجموعه ای از تغییرات در مستندات درباره کد است
[ 1. سیستم نسخه سازی ]
در [ 1. Scancode-Toolkit Command Line Options -> 2. Initiate Versioning Structure] موضوع نسخه سازی گزینه های Command Line ذکر شده است. همین امر برای سایر بخش‌های اسناد نیز ضروری است که حاوی دستورات/اطلاعات خاص نسخه هستند که در غیر این صورت باعث سردرگمی می‌شوند.
[ 2. تنظیم استانداردها و آزمایشات مستندات ]
این اسناد قبلاً دارای آزمایشاتی برای spinx-build هستند (همه صفحات را می سازد و خطاهای نحوی Sphinx را در سراسر آن بررسی می کند) و بررسی پیوند (تمام پیوندهای سایر صفحات وب را از اسناد بررسی می کند) با یکپارچه سازی مداوم از طریق Travis-CI. (که توسط من در این درخواست کشش شماره 17 اضافه شده است) اکنون به بررسی های بیشتری برای پرده های خاص در متن بازسازی شده و سایر استانداردها نیاز دارد. این را می توان با restructuredtext-lint به دست آورد، اما به تحقیقات بیشتری نیاز دارد و به عنوان بخشی از پروژه GSoD من انجام خواهد شد.
[ 3. افزودن بخش «شروع به کار» ]
این به عنوان یک بخش شروع برای تازه واردان عمل می کند و حاوی مجموعه ای از اساسی ترین و مهم ترین اسناد برای شروع با پروژه های Aboutcode است. هر پروژه Aboutcode دارای این بخش از جمله Scancode-Toolkit، Scancode-Workbench، Deltacode و موارد دیگر خواهد بود.
[ 4. بازسازی با توجه به 4 تابع سند ]
مستندات موجود به صراحت در 4 تابع سند - آموزش ها، نحوه انجام کارها، مرجع و توضیحات ساختاربندی نشده است. من پیشنهاد می‌کنم آنها را بر این اساس ساختاربندی کنیم و اطلاعات/توضیحات/اشاره‌های بیشتری را هرچه لازم است اضافه کنیم. این برای تمام پروژه های AboutCode و مستندات آنها صادق است. در زیر دو نمونه از بازسازی اسناد Scancode-Toolkit وجود دارد که پیشنهاد کرده‌ام و می‌خواهم در این پروژه ادامه دهم. تغییرات مشابهی در بقیه اسناد انجام خواهد شد.
[ 5. بازسازی صفحه توسعه (Scancode-Toolkit) ]
اطلاعات بیشتر در مورد کد/APIها می‌تواند اضافه شود تا آن را برای توسعه‌دهندگان دوست‌دارتر کند. می‌توان پیوندهایی به بخش [ 2. بحث در مورد توضیح اسکن کد] در بالا وجود داشت. این توضیح نحوه عملکرد اسکن را به کدی که برای انجام اسکن استفاده می کند پیوند می دهد. مانند این پوشه ها شامل بخش های مختلف Scancode-Toolkit هستند، استفاده فردی آنها را می توان با API ها همراه با بحث در مورد نحوه عملکرد اسکن کد توضیح داد.
- [کلیدکد: افزونه‌هایی برای اسکن مجوزها، حق چاپ، آدرس‌های اینترنتی، ایمیل‌ها]
- [کد مشترک: کلاس های کمکی و توابع]
- [extractcode: استخراج فرمت های مختلف آرشیو]
- [formtedcode: قالب‌بندی خروجی برای فرمت‌های مختلف فایل خروجی]
- [کد مجوز: کد شناسایی مجوز]
- [packedcode: تجزیه فرمت های مختلف بسته]
- [ کد پلاگین : کلاس های معماری پلاگین ها ]
- [خلاصه کد: اسکن در مجوزهای شناسایی شده را خلاصه می کند]
- [ textcode : تجزیه متن را کنترل می کند ]
- [نوع کد: تعیین نوع فایل را انجام می دهد]
- [اسکن کد: CLI و API برای اسکن کد، بخش اصلی]
این بخش فرعی حاوی اطلاعات/APIهای دقیق در مورد این بخش‌های scancode-toolkit در زیربخش‌ها خواهد بود. دستورالعمل های توسعه در صفحه دیگری یا بخش دیگری با بخش های فرعی کوچکتر وجود دارد.
[ 6. بازسازی صفحه پرسش‌های متداول (Scancode-Toolkit)]
صفحه پرسش‌های متداول در حال حاضر دارای سؤالاتی است که می‌توان به آنها پاسخ بهتری داد و باید به‌صورت مجزای نحوه انجام، آموزش‌ها و اسناد مرجع به طور جداگانه ساختار داده شود.
- ScanCode چگونه کار می کند؟ این موضوع در [2. بحث در مورد توضیح اسکن کد] ارجاع شده است و یک بخش کاملاً جداگانه در جزئیات بسیار بیشتر خواهد بود.
- چگونه قوانین مجوز جدید را برای تشخیص پیشرفته اضافه کنیم؟ این موضوع قبلاً در بهبود روش‌های موجود بحث شده است، اسناد به آنجا منتقل خواهند شد.
- چگونه یک قانون جدید تشخیص مجوز اضافه کنیم؟ این را می توان به صورت جداگانه در یک پست دیگر "چگونه به" تبدیل کرد و می توان در مورد آن توضیح داد.
- چگونه با توسعه شروع کنیم؟ در حال حاضر یک صفحه توسعه جداگانه وجود دارد و اطلاعات بسیار با هم تداخل دارند. بازسازی صفحه توسعه قبلاً در بالا مورد بحث قرار گرفته است.
- مراحل کاهش نسخه جدید این می تواند به یک "چگونه نسخه جدید را برش دهیم" جداگانه تبدیل شود.
- سؤالات متداول بیشتری را بیابید که به سؤالات عمومی در مورد پروژه پاسخ می دهند و در دسته بندی «چگونه»/«آموزش» قرار نمی گیرند.