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

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

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

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

AboutCode

כתב טכני:

איאנסינה

שם הפרויקט:

הפניה לאפשרויות של שורת הפקודה בערכת הכלים לסריקה וארגון מחדש של מבנה התיעוד של aboutCode בכתובת aboutcode.readthedocs.io

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[ 6. שימוש עסקי בתבניות פלט של Scancode ]

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

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

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

[ 2. ארגן מחדש את המבנה של מסמכי aboutCode ]

חלק זה כולל מגוון של שינויים במסמכי התיעוד בנושא aboutcode

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

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

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

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

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

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

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

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

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

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

• [ cluecode : יישומי פלאגין לסריקת רישיונות, זכויות יוצרים, כתובות URL, הודעות אימייל ]
• [ Commoncode : מחלקות ופונקציות של helper]
• [ קוד חילוץ : מחלץ פורמטים שונים של ארכיון ]
• [ formattedcode : עיצוב פלט לפורמטים שונים של קובצי פלט ]
• [ Licensecode : קוד זיהוי רישיון ]
• [ קוד אריזה : ניתוח פורמטים שונים של חבילה ]
• [ Plugincode : מחלקות לארכיטקטורת יישומי פלאגין ]
• [ summarycode : מסכם את הסריקה ברישיונות שזוהו ]
• [ קוד טקסט : מטפל בניתוח טקסט ]
• [ typecode : מטפל בהחלטות של סוג הקובץ ]
• [scancode : CLI ו-API לסריקת קוד, החלק המרכזי ]

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

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

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

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