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

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

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

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

AboutCode

כתב טכני:

איינסינה

שם הפרויקט:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[ 5. תבניות פלט והדוגמאות שלהן ]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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