פרויקט משותף לפיילוט של ביצועים

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

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

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

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

מופשט:

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

הצעה:

  1. סקירה כללית: התיעוד של תוכנית הפיילוט לפעילות משותפת קיים כרגע בכמה פורמטים שונים. אלה כוללים ספרי PCP בפורמט מסמך דיגיטלי, API ל-REST בפורמט דף ניהול ומדריכי pbench בפורמט Markdown. לכן, בקבוצת התחזוקה הנוכחית של הארגון זיהו שהם זקוקים לפתרון ללא תחזוקה עד כמה שניתן, ושמאפשר לקהילת המפתחים להתמקד לחלוטין בתחזוקת התוכן שלו בצורה יעילה וקלה. לכן, בהתאם לצרכים הנוכחיים של הארגון, איישם את המטרות הבאות בעונה זו של Google Docs:

    1. המרת תוכן של ספר מסמכים לפורמט reStructuredText ואירוח התוכן באתר Readthedocs.
    2. המרת התיעוד של REST API מדף הניהול לפורמט ידידותי למפתחים, כלומר לפורמט reStructuredText, ואירוח התיעוד באתר Readthedocs.
    3. המרת תוכן MarkDown של פורמט reStructuredText ואירוח התוכן באתר Readthedocs.
    4. יעדי מתיחה נועדו לשפר את הדיאגרמות שמופיעות בתיעוד.

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

אאפשר לארגון להתגבר על המגבלות במהלך ה-GSoD באמצעות פורמט reStructuredText, Read the Docs (RTD) ו-Sphinx.

קראו את Docs (RTD) כדי לפשט את תיעוד התוכנה על ידי אוטומציה של בנייה, ניהול גרסאות ואירוח המסמכים שלנו עבורנו. זוהי פלטפורמת אירוח לתיעוד שנוצר על ידי הספינקס. היא משתמשת בעוצמה של הספינקס ומוסיפה בקרת גרסאות, חיפוש טקסט מלא ותכונות שימושיות נוספות. הוא שולף קוד וקובצי מסמכים מ-Git, Mercurial או Subversion, ואז יוצר ומארח את התיעוד שלנו. נשתמש ב-GitHub בפרויקט שלנו כי זו המערכת הנפוצה ביותר לגישה לקוד.

כדי להתחיל, ניצור חשבון 'לקריאת חשבון Docs', ונקשר את חשבון GitHub. אחר כך נבחר את מאגר GitHub שעבורו אנחנו רוצים ליצור תיעוד, ובשלב זה יתרחש הקסם.

קריאה של מסמכי Docs תגרום: - שכפול המאגר שלנו. - פיתוח גרסאות HTML, PDF ו-ePub של המסמכים שלנו מהסניף הראשי שלנו. - ליצור אינדקס של התיעוד שלנו כדי לאפשר חיפוש טקסט מלא. - יצירת אובייקטי גרסה מכל תג והסתעפות במאגר שלנו, כדי שנוכל לארח גם אותם באופן אופציונלי. - הפעלת תגובה לפעולה מאתר אחר (webhook) במאגר הנתונים שלנו. כך, כשאנחנו שולחים קוד לסניף כלשהו, המסמכים שלנו נוצרים מחדש.

Sphinx הוא מחולל מסמכים מהימן שכולל תכונות נהדרות ונהדרות לכתיבת מסמכים טכניים, כולל: - יצירת דפי אינטרנט, קובצי PDF להדפסה, מסמכים עבור קוראים אלקטרוניים (ePub) ועוד, מאותו מקור. - אנחנו יכולים להשתמש ב-reStructuredText כדי לכתוב מסמכים. - מערכת נרחבת של הצלבת קוד ותיעוד. - דוגמאות קוד מודגשות מבחינת תחביר. - סביבה עסקית תוססת של תוספים של צד ראשון ושל צד שלישי.

אתחיל בהמרה של שני ספרי ה-PCP שנמצאים בפורמט docbook לפורמט rst, לאחר ההמרה של תיעוד ה-API ל-REST מפורמט דף man לפורמט rst, ואז המרה של תוכן תגי ה-Pbench לפורמט rst ובסופו של דבר אירוח כל הספרים באתר Readthedocs. מטרת ההתקדמות היא לשפר את הדיאגרמות בתיעוד.

2.1. המרה לפורמט reStructuredText: השלב הראשון יהיה להמיר את תוכן התיעוד לפורמט reStructuredText. לכל פרק יהיה קובץ rst נפרד, שיכיל את תוכן הפרק הזה בלבד. לדוגמה, הספר 'מדריך למשתמש של טייס משותף' ו'מדריך למנהל' כולל שמונה פרקים. המשמעות היא שיהיו שמונה קובצי rst שונים שמתאימים לשמונה הפרקים האלה. שם קובץ ה-rst יהיה זהה לשם הפרק כדי למנוע בלבול בעתיד. תוצג רשימה של דמויות, טבלאות ורשימות של דוגמאות בשלושה קובצי rst שונים. התוכן הראשי יכלול היפר-קישורים באופן יסודי, כפי שהוא קיים כרגע. אותו הדבר ישמש לתיעוד של API ל-REST ולתוכן Pbench. כל הדברים הנחוצים, כמו גופן מודגש, נטוי, עם קו תחתון, תבליטים, טבלאות, גודל גופן, סגנון קוד, גודל תמונה, יישור וכו', יטופלו תוך כדי המרת התוכן לפורמט rst.

2.2. שילוב של rst עם Sphinx:

ReadtheDocs משתמש בברירות המחדל Sphinx ו-reStructuredText (rst). מאחר שה-Sphinx מותקן מראש במערכת שלי, אתחיל ביצירת ספרייה בתוך הפרויקט (בשם 'מסמכי תיעוד של פיילוט משותף של ביצועים') לשמירת המסמכים: $ cd /path/to/project $ mkdir docs

לאחר מכן, מריץ את sphinx-quickstart: $ cd docs $ sphinx-quickstart

בהתחלה הקצרה הזו מוסבר איך ליצור את ההגדרות הנדרשות. ברוב המקרים נוכל לקבל רק את הגדרות ברירת המחדל (אבל כשיש צורך, נוכל לבצע את השינויים החיוניים בקובץ התצורה). כאשר התהליך יסתיים, יהיו לנו index.rst, קובץ conf.py וכמה קבצים אחרים. ב-index.rst, אוסיף את כל הפרטים הנדרשים על הפיילוט המשותף לביצועים ואצור כותרות לספרים, למסמכי התיעוד ל-API ל-REST ולמדריכים ל-Pbench. כשהמשתמש ילחץ על אחת מהכותרות, ייפתחו כל חומרי התיעוד שתחת הכותרת הזו.

הערה: העיצוב של דף האינדקס יהיה בהתאם להסכמת המנטורים וחברי הקהילה וישונה בהתאם לצרכים ולדרישות.

ה-index.rst יהיה מובנה בתוך index.html בספריית פלט התיעוד שלנו (בדרך כלל _build/html/index.html). ברגע שיהיה לנו תיעוד של Sphinx במאגר ציבורי, נוכל להתחיל להשתמש ב-Read the Docs על ידי ייבוא המסמכים שלנו.

כאשר נוסיף קובץ rst. לתיעוד שלנו, המערכת תיצור שלושה קבצים נוספים, אחד בתיקייה doctree עם סיומת doctree, שני בתיקיית Html עם סיומת html והקובץ השלישי בתיקייה html/_sources עם הסיומת rst.txt.

  1. אירוח המסמך: אירוח המסמכים באינטרנט מורכב משני שלבים: 1. ייבוא המסמכים: בשלב הראשון אקשר את חשבון Read The Docs ל-GitHub ואייבא את פרויקט התיעוד שלנו ליצירה. 2. יצירת התיעוד: תוך מספר שניות מהשלמת תהליך הייבוא, הקוד יאוחזר באופן אוטומטי מהמאגר הציבורי שלנו, והמסמכים ייבנו.

  2. WEBHOOKS: השיטה העיקרית ש-Read the Docs משתמשת בה כדי לזהות שינויים במסמכי התיעוד ובגרסאות היא באמצעות שימוש ב-webhooks. תגובות לפעולה מאתר אחר (webhook) מוגדרות באמצעות ספק המאגר שלנו, כמו GitHub. לאחר כל התחייבות, מיזוג או שינוי אחר במאגר שלנו, נשלחת הודעה לגבי 'קריאת המסמכים'. כשאנחנו מקבלים התראת webhook, אנחנו קובעים אם השינוי קשור לגרסה פעילה של הפרויקט שלנו, ואם כן, מופעל build עבור הגרסה הזו.

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

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

כדי למלא את המטרה הזו, אני משתמש ב-draw.io (או בכל כלי אחר בהסכמת המנטור).

בתור הוכחת היתכנות, שיפרתי את אחד מהתרשימים המוצגים בתיעוד בעזרתdraw.io. הוא נמצא כאן: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

הוכחת קיומו

המרתי חלק קטן מספר ה-PCP (בפורמט docbook) לפורמט rst, ואירחתי אותו באתר Readthedocs. הוא נמצא כאן.

אתר - https://pcp-books.readthedocs.io/en/minute/ קוד - https://github.com/arzoo14/PCP_Books_Demo

הגדרתי webhooks גם במאגר הקוד. בעזרת ההגדרות האלה, השינויים שבוצעו במאגר הקוד ישתקפו באתר.

ציר זמן ופרטים

תקופת גיבוש של הקהילה [ 17 באוגוסט - 13 בספטמבר 2020 ]

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

תקופת הפיתוח של המסמך [ 14 בספטמבר עד 30 בנובמבר 2020 ]

***מ-14 בספטמבר 2020 עד 20 בספטמבר 2020 [WEEK 1] המרת התוכן של ספר המסמכים לפורמט rst בארבעת הפרקים הראשונים של הספר 'משתמשים ואדמינים'.

***מ-21 בספטמבר 2020 עד 27 בספטמבר 2020 [WEEK 2] המרה של התוכן בספר המסמכים לפורמט rst בארבעת הפרקים הבאים של הספר 'משתמשים ואדמינים'.

***מ-28 בספטמבר 2020 עד 4 באוקטובר 2020 [WEEK 3] המרת התוכן של ספר המסמכים לפורמט rst בכל ארבעת הפרקים של ספר המדריך למתכנתים.

***מ-5 באוקטובר 2020 עד 11 באוקטובר 2020 [WEEK 4] - אירוח ספרי PCP באתר Readthedocs. - המרת התיעוד של API ל-REST מ-man page לפורמט rst. במהלך התקופה הזו, יוצג גם דף הנחיתה הראשי. - כתיבת בלוג (של פרויקט GSoD שלי) בשלושת השבועות האחרונים והשבוע הנוכחי.

***מ-12 באוקטובר 2020 עד 18 באוקטובר 2020 [WEEK 5] המרת האינדקס של סדרת זמן ניתנת להתאמה לפורמט rst. האינדקס של סדרת הזמן שניתן להתאמה כולל את הפריטים הבאים: GET /series/query , GET /series/values, GET /series/assets , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/loads

***מ-19 באוקטובר 2020 עד 25 באוקטובר 2020 [WEEK 6] המרה של אינדקס שירותי המארח של PMAPI לפורמט rst. האינדקס של PMAPI Host Services כולל את הפרטים הבאים: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***מ-26 באוקטובר 2020 עד 1 בנובמבר 2020 [WEEK 7] - אם יש משהו בשבועות האחרונים, נטפל בו קודם. - אירוח תיעוד של API ל-REST באתר Readthedocs. - כתיבת בלוגים (של פרויקט GSoD שלי) במהלך השבועיים האחרונים והשבוע הנוכחי.

***מ-2 בנובמבר 2020 עד 8 בנובמבר 2020 [WEEK 8] המרה של תוכן העיצוב לפורמט rst במדריכי Pbench.

***מ-9 בנובמבר 2020 עד 15 בנובמבר 2020 [WEEK 9] - המשך בהמרת התוכן השיווקי לפורמט rst בפורמט rst. - אירוח של מדריכי pbench באתר Readthedocs. - כתיבת בלוג (של פרויקט GSoD שלי) בשבוע האחרון ובשבוע הנוכחי.

***מ-16 בנובמבר 2020 עד 22 בנובמבר 2020 [WEEK 10] - הטמעה של פונקציונליות החיפוש בדף האינדקס לצורך חיפוש תוכן מהשם שלו באתרים. - תחילת היעדים של ההמשך.

***מ-23 בנובמבר 2020 עד 30 בנובמבר 2020 [WEEK 11] - שיפור של כל התרשימים שמופיעים במסמכי התיעוד. - כתיבת הבלוג הסופית (של פרויקט GSoD שלי) בשבוע האחרון ובשבוע הנוכחי. - בדיקה אם ה-codebase תואם לתקני התכנות או לא. אם לא, צריך לשנות אותם בהתאם לתקנים.

תקופת האישור של הפרויקט [ 30 בנובמבר - 5 בדצמבר 2020 ]

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