פרויקט מידע על קוד

בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.

סיכום הפרויקט

ארגון קוד פתוח:

AboutCode

כותב טכני:

ayansinha

שם הפרויקט:

חומר עזר לאפשרויות של שורת הפקודה ב-scancode-toolkit וארגון מחדש של המבנה של מסמכי התיעוד של AboutCode בכתובת aboutcode.readthedocs.io

משך הפרויקט:

אורך רגיל (3 חודשים)

תיאור הפרויקט

[ 1. אפשרויות של שורת הפקודה של Scancode-Toolkit ]

ב-Scancode-Toolkit יש מגוון אפשרויות של שורת פקודה להתאמה אישית של אופן הסריקה, פורמט הפלט ועוד כמה אפשרויות כמו תוספים אחרי הסריקה. נכון לעכשיו, אין תיעוד מתאים לאפשרויות האלה, והן זמינות רק באמצעות הדגל ‎--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 יש דגלים שמאפשרים לציין פורמטים שונים של פלט שבהם ייווצרו תוצאות הסריקה. הם -
  החלק הזה
• הסבר מפורט על פורמטי הפלט
• לספק דוגמאות לפורמטים של הפלט
• לתת קישורים אחרים שמתאימים לפורמט הפלט ולשימוש בו
• איך תוצאות הסריקה מאוחסנות בקובצי הפלט. הקישור הזה מוביל גם למאמר בנושא איך נוצרים הפורמטים השונים האלה, שיוסבר ב[ 2. דיונים עם הסברים על סריקת קוד ].

‫[ 6. שימוש עסקי בפורמטים של פלט של קודי סריקה ]

• מטרות: להסביר את תרחישי השימוש העסקיים של פורמטים של פלט Scancode ברשימת הרעיונות של GSoD, פורמטים של פלט Scancode מוזכרים כרעיון לדוגמה. בקטע הזה מיושם אותו הדבר.
• הערה: כדי לבצע את החלק הזה, נדרשת עזרה משמעותית מהמנטור בנוגע לקלט ולתרחישים שונים לשימוש עסקי ב-Scancode-Toolkit.

‫[ 7. איך פלטים כאלה משמשים בפרויקטים אחרים של AboutCode לניתוח נוסף ]

• המטרה: בקטע הזה נספק סיכום בסיסי של האופן שבו אפשר להשתמש בתוצאות הסריקה של scancode-toolkit במקרים שונים, ושל הכלים של Aboutcode שמספקים פונקציונליות כזו.
• סקירה כללית בסיסית:
• Scancode-Workbench בחלק הזה מוסבר איך להציג את התוצאות באמצעות אפליקציית שולחן העבודה, ומופיעים קישורים למסמכי Scancode-Workbench לקבלת תמיכה נוספת בנושא. אני אוסיף את המסמכים הנדרשים ל-scancode-workbench אם יהיה צורך בכך.
• ‫Deltacode איך Deltacode משתמש בתוצאות של scancode כדי לקבוע את ההבדלים ברמת הקובץ בין שני codebases.

[ 2. ארגון מחדש של המבנה של AboutCode Documentation ]

החלק הזה כולל שורה של שינויים במסמכי Aboutcode

[ 1. מערכת לניהול גרסאות ]

‫In [ 1. אפשרויות שורת הפקודה של Scancode-Toolkit -> ‫2. Initiate Versioning Structure] the issue of versioning the Command Line options are mentioned. אותו הדבר נכון גם לגבי חלקים אחרים במסמכי התיעוד שמכילים פקודות או מידע שספציפיים לגרסה מסוימת, ועלולים ליצור בלבול אם לא יצוין שהם ספציפיים לגרסה.

‫[ 2. הגדרת תקנים לבדיקות ולתיעוד ]

במסמכי התיעוד כבר יש בדיקות ל-spinx-build (בניית כל הדפים ובדיקה של שגיאות בתחביר Sphinx בכל הדפים) ולבדיקת קישורים (בדיקת כל הקישורים לדפי אינטרנט אחרים מתוך התיעוד) עם אינטגרציה רציפה דרך Travis-CI. (נוסף על ידי בבקשת המיזוג הזו מספר 17) עכשיו צריך לבצע עוד בדיקות ספציפיות של linting ב-reStructured Text ובתקנים אחרים. אפשר להשיג את זה באמצעות 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 כדי להסביר איך כל אחת מהן פועלת, בשילוב עם ההסבר על אופן הפעולה של scancode.

• [ 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 ]

בסעיף המשנה הזה יופיע מידע מפורט או ממשקי API על החלקים האלה של scancode-toolkit, בסעיפי משנה בהתאם. ההנחיות לפיתוח יופיעו בדף אחר או בקטע אחר עם קטעי משנה קטנים יותר.

‫[ 6. ארגון מחדש של דף השאלות הנפוצות (Scancode-Toolkit) ]

בדף השאלות הנפוצות יש כרגע שאלות שאפשר לענות עליהן בצורה טובה יותר, והוא צריך להיות מובנה כמסמכי הדרכה, מדריכים וחומר עזר נפרדים.

• איך ScanCode עובד? הבעיה הזו מוזכרת ב[ 2. דיונים שמסבירים את סריקת הקוד ] ויהיו קטע נפרד לגמרי עם הרבה יותר פרטים.
• איך מוסיפים כללי רישוי חדשים לזיהוי משופר? הבעיה הזו כבר נדונה במאמר 'שיפור המדריכים הקיימים', והתיעוד יועבר לשם.
• איך מוסיפים כלל חדש לזיהוי רישיונות אפשר להפוך את זה לפוסט נוסף של 'איך עושים את זה' בנפרד, ולפרט יותר.
• איך מתחילים לפתח? כבר קיים דף פיתוח נפרד, ויש חפיפה רבה בין המידע שמופיע בו לבין המידע שמופיע כאן. כבר דיברנו למעלה על השינוי במבנה של דף הפיתוח.
• שלבים להשקת גרסה חדשה אפשר להפוך את זה למאמר נפרד בנושא 'איך להשיק גרסה חדשה'.
• אפשר למצוא תשובות לשאלות נפוצות נוספות שלא מתאימות לקטגוריות 'איך עושים' או 'מדריך', אלא עוסקות בשאלות כלליות לגבי הפרויקט.