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

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

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

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

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

תקציר:

אתר קהילה ממלא תפקיד חיוני בארגון קוד פתוח, כי הוא מפיץ את הרעיון של המוצרים שהקהילה מספקת, התרומות היקרות שלה, הכישורים שלה, המסמכים שלה, המדריכים שלה וכו'. לכן, הפרויקט שלי יתבסס על העברת התוכן של תחומי הספרים בפרויקט ועדכון שלו, כלומר תוכן docbook, מסמכי REST API ותוכן pbench markdown, לפורמט reStructuredText כדי שניתן יהיה לארח אותו באתר החדשני והקהילתי readthedocs.io. הפרויקט הזה יעזור גם לתורמים מהקהילה, כי הוא יאפשר להם לשנות ולהרחיב את התוכן הזה בקלות רבה יותר. בנוסף, כמטרה שאפתנית, נשתדל לשפר את התרשימים במסמכי העזרה כדי שיראו מקצועיים יותר.

הצעה:

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

    1. המרת תוכן של docbook לפורמט reStructuredText והרצה שלו באתר readthedocs.
    2. המרת מסמכי התיעוד של ה-API ל-REST מדף עזרה לפורמט ידידותי למפתחים, כלומר פורמט reStructuredText, והאירוח שלו באתר readthedocs.
    3. המרת תוכן Markdown של pbench לפורמט reStructuredText והרצה שלו באתר readthedocs.
    4. יעדי העל יכולים להיות שיפור התרשימים שמופיעים במסמכי העזרה.

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

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

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

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

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

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

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

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

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

ברירות המחדל של ReadtheDocs הן Sphinx ו-reStructuredText (rst). מכיוון ש-Sphinx מותקן מראש במערכת שלי, אתחיל ביצירת ספרייה בתוך הפרויקט (שנקראת 'מסמכי עזרה של Performance Co-Pilot') שתשמש לאחסון המסמכים: $ 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 למסמכי התיעוד שלנו, ייווצרו שלושה קבצים אחרים, אחד בתיקיית doctrees עם הסיומת .doctree, השני בתיקיית Html עם סיומת .html והשני בתיקיית html/_sources עם הסיומת .rst.txt.

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

  2. Webhooks:‏ השיטה העיקרית שבה Read the Docs משתמשת כדי לזהות שינויים במסמכים ובגרסאות היא באמצעות webhooks. אנחנו מגדירים את ה-webhooks אצל ספק המאגר שלנו, כמו GitHub, וכל פעם שמתבצע השמירה, מיזוג או שינוי אחר במאגר, אנחנו מקבלים התראה ב-Read the Docs. כשאנחנו מקבלים התראה מ-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/previous/ קוד – https://github.com/arzoo14/PCP_Books_Demo

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

לוח זמנים ותוצרים

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

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

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

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

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

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

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

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

***מ-19 באוקטובר 2020 עד 25 באוקטובר 2020 [שבוע 6] המרת האינדקס של שירותי המארח של PMAPI לפורמט rst. אינדקס שירותי המארח של PMAPI כולל את הנושאים הבאים: 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 /api/metrics

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

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

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

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

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

תקופת סיום הפרויקט [30 בנובמבר עד 5 בדצמבר 2020 ]

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