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

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

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

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

AboutCode

כותבים טכניים:

ayansinha

שם הפרויקט:

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

אורך הפרויקט:

אורך סטנדרטי (3 חודשים)

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

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

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

[ 1. כל האפשרויות הזמינות דרך שורת הפקודה ]

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

[ 2. יצירת מבנה ניהול גרסאות ]

• היעד: הפעלת מערכת ניהול גרסאות כדי לתחזק באופן תקין את השינויים ב-API ובאפשרויות של גרסאות שונות.
• הבעיה: נכון לעכשיו, המסמכים בוויקי ובדפי ReadTheDocs מיועדים לגרסאות ישנות יותר, ויש צורך בשינוי מבני משמעותי.
• סקירה כללית בסיסית: חלקי ערכת הכלים של קוד הסריקה שעודכנו או שאפשר לעדכן בגרסה הזו הם
• אפשרויות של שורת הפקודה
• ממשקי API
• תיעוד (עוד לא התחיל) אפשרויות שורת הפקודה וממשקי ה-API משתנים בגרסאות ובמהדורות, וגם המסמכים צריכים להתעדכן בהתאם, אחרת ייווצר בלבול רב בקרב המשתמשים. הכלי של שורת הפקודה [ --help ] כבר מעודכן לכל שינוי באפשרויות, וניתן להשתמש בו כדי לשכפל את ניהול הגרסאות במסמכים.

[ 3. איך אפשר להשתמש באפשרויות האלה במקרים שונים ]

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

[ 4. איך האפשרויות האלה משנות את הסריקה ואת הפלט ]

• מטרה: בקטע הזה נספק סיכום בסיסי של הדרכים שבהן אפשר להשתמש בתוצאות הסריקה של scancode-toolkit למטרות שונות, ונסביר על הכלים של Aboutcode שמספקים פונקציונליות כזו.
• סקירה כללית בסיסית: האפשרויות משנות את האופן שבו מתבצעת הסריקה. מקרה בסיסי של ברירת מחדל יוצג בקטע הפותח [ 1. כל האפשרויות הזמינות דרך שורת הפקודה ] ובקטע הזה נסקור את השינויים שכל האפשרויות מביאות לתרחיש ברירת המחדל הזה.

[ 5. פורמטים של פלט ודוגמאות להם ]

• מטרה: בקטע הזה נספק סיכום בסיסי של הדרכים שבהן אפשר להשתמש בתוצאות הסריקה של scancode-toolkit למטרות שונות, ונסביר על הכלים של Aboutcode שמספקים פונקציונליות כזו.
• סקירה כללית בסיסית: ל-Scancode-Tool יש דגלים לציון פורמטים שונים של פלט שבהם תוצאות הסריקה יופקו. אלה הם -
  החלק הזה
• הסבר מפורט על פורמטים של פלט
• לתת דוגמאות לפורמטים של הפלט
• מספקים קישורים אחרים שתואמים לפורמט הפלט ולשימוש בו
• האופן שבו תוצאות הסריקה מאוחסנות בקובצי הפלט. הקישור הזה מפנה גם ל'איך נוצרים הפורמטים השונים האלה', שבו נסביר את הנושא בקטע [ 2. דיונים שמסבירים על סריקת קוד ].

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

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

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

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

[ 2. סידור מחדש של המבנה של מסמכי התיעוד של AboutCode ]

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

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

ב-[ 1. אפשרויות שורת הפקודה של Scancode-Toolkit -> 2. הפעלת מבנה ניהול הגרסאות] הבעיה בניהול גרסאות של האפשרויות של שורת הפקודה מוזכרת. צריך לעשות את אותו הדבר גם בחלקים אחרים של המסמך, שמכילים פקודות או מידע ספציפיים לגרסה, שעלול לגרום לבלבול.

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

במסמכי התיעוד כבר יש בדיקות ל-spinx-build (יצירת גרסאות build של כל הדפים ובדיקת שגיאות בתחביר של Sphinx לאורך כל התהליך) ולבדיקת קישורים (בדיקת כל הקישורים לדפי אינטרנט אחרים מהמסמכים) באמצעות אינטגרציה רציפה דרך Travis-CI. (הוספתי את זה בבקשת המשיכה הזו מס' 17) עכשיו צריך עוד בדיקות לזיהוי שגיאות ספציפיות ב-reStructured Text ובתקנים אחרים. אפשר לעשות זאת באמצעות restructuredtext-lint, אבל צריך עוד מחקר והוא יבוצע כחלק מהפרויקט שלי ב-GSoD.

[ 3. הוספת קטע 'תחילת העבודה' ]

הקטע הזה ישמש כקטע התחלה למשתמשים חדשים, ויכלול אוסף של המסמכים הבסיסיים והחשובים ביותר לתחילת העבודה עם Aboutcode Projects. כל פרויקט ב-Aboutcode יכלול את הקטע הזה, כולל Scancode-Toolkit, ‏ Scancode-Workbench, ‏ Deltacode ועוד.

[ 4. ארגון מחדש בהתאם ל-4 פונקציות המסמך ]

מסמכי התיעוד הקיימים לא מובנים במפורש מ-4 הפונקציות של המסמכים: מדריכים, מדריכים, חומרי עזר והסברים. אני מציע לבנות אותם בהתאם, ולהוסיף מידע נוסף/הסברים/הפניות לפי הצורך. המדיניות הזו חלה על כל הפרויקטים של AboutCode ועל המסמכים שלהם. בהמשך מפורטות שתי דוגמאות למבנה המחודש של חומרי העזר של Scancode-Toolkit שאני מציע וארצה להמשיך לפתח בפרויקט הזה. שינויים דומים יבוצעו בשאר המסמכים.

[ 5. ארגון מחדש של דף הפיתוח (Scancode-Toolkit) ]

אפשר להוסיף מידע נוסף על הקוד או על ממשקי ה-API כדי להפוך אותם למתאימים יותר למפתחים. יכולים להיות קישורים אל [ 2. דיונים לגבי הקטע Code Scanner ] שלמעלה. כך אפשר לקשר את ההסבר על אופן הפעולה של הסריקה לקוד שבו נעשה שימוש כדי לבצע את הסריקה. התיקיות האלה מכילות חלקים שונים של ערכת הכלים של scancode, וניתן להרחיב על השימוש בכל אחת מהן באמצעות ממשקי ה-API, בשילוב עם הדיון על אופן הפעולה של scancode.

• [ cluecode : יישומי פלאגין לרישיונות סריקה, זכויות יוצרים, כתובות URL, אימיילים ]
• [ commoncode : helper classes and functions]
• [ קוד חילוץ : מחלץ פורמטים שונים של ארכיון ]
• [ formattedcode : output formatting for different output file formats ]
• [ licensedcode : licence detection code ]
• [ packagedcode : parsing various package formats ]
• [ plugincode : classes for the plugins architecture ]
• [ Summarycode : מסכם את הסריקה ברישיונות שזוהו ]
• [ textcode : מטפל בניתוח טקסט ]
• [ typecode : handles file type determinations ]
• [ scancode : CLI and API to scancode, the core part ]

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

[ 6. שינוי המבנה של דף השאלות הנפוצות (Scancode-Toolkit) ]

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

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