בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- SymPy
- כותבים טכניים:
- Soumi7
- שם הפרויקט:
- עקביות בין מחרוזות docstring – מסמכי תיעוד של Sympy
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
תקציר :
המצב הנוכחי של מסמכי התיעוד של Sympy והעבודה הקודמת :
העבודה על יצירת מדריך סגנון רשמי ל-SymPy הושלמה.
בפרויקט GSoD של Lauren Glattly נוצר מדריך סגנון ל-docstrings של SymPy, שזמין במדריך הסגנון של תיעוד SymPy.
ערכנו את docstrings ב-Special submodule ובקובץ solvers.py בהתאם להנחיות של מדריך הסגנון החדש
עדיין היה צריך לערוך את כל שאר תיאורי הקוד בקוד הבסיסי כך שיתאימו גם למדריך הסגנון החדש.
העבודה המוצעת :
רוב תיאורי ה-docstrings ב-SymPy עדיין לא תואמים למדריך הסגנון העדכני. מטרת הפרויקט היא לעדכן את מחרוזות ה-docstring ב-SymPy בהתאם למדריך הזה.
דיברתי על הפרויקט עם המנטורים. זה הקישור לדיון.
הוחלט שעריכת docstrings בקוד של sympy בהתאם למדריך הסגנון העדכני היא משימה גדולה, ושהפרויקט צריך להיות מוגבל אליה.
במסגרת העבודה שלי בפרויקט, אטמיע את המדריך החדש כדי לעדכן את תוכן התיעוד הקיים, תוך איסוף של אי-עקביות אחרות, כמו שימוש בשפה או מונחים, וטיפול בהן.
אפשר לשנות או לקבוע את הסדר של סעיפי המשנה הקיימים בשלב מאוחר יותר או כמשימה נפרדת.
הדגמת ההבדלים בתוצאות כשמעבירים ערכים שונים לפרמטרים, על ידי הוספת דוגמאות נוספות וקטעי פרמטרים.
מוסיפים דוגמאות מאתגרות לקטע 'מלכודות'.
תרומות: - #17887 : עבודה על בעיה מס' 17887: הוספת קטעי docstring חסרים במודול המשנה המיוחד. הוספתי את הקטע 'פרמטרים ודוגמאות' שחסרים בחלק מהפונקציות של תת-מודול ה-Specials, ש-L ערך. Glattly פועל לפי מדריך הסגנון העדכני ביותר ומשמש כמודל לתיעודים עתידיים של docstrings.
זה הקישור לבקשה המצורפת שצורפה : https://github.com/sympy/sympy/pull/19334
- #19591 : Issue #19591 tracks the Documentation style guide. הוספתי PR כדי לערוך את ה-docstring של Core.sympify כדי לפעול בהתאם למדריך הסגנון העדכני. הוספתי הסברים מובְנים ודוגמאות לשימוש בפרמטרים שונים.
הנה הקישור לכתבי הציבור: https://github.com/sympy/sympy/pull/19613
יעדי הפרויקט
ציר זמן לפני 17 באוגוסט :
- ממשיכים לתרום לארגון.
- כדאי להכיר יותר את מסמכי התיעוד למשתמשים ואת הגרסה הנוכחית של sympy.
- מקבלים מידע על שיטות ומיומנויות שיעזרו לכם להטמיע את הפרויקט.
יצירת קשר עם הקהילה : (17 באוגוסט עד 13 בספטמבר 2020)
- מגדירים ערוץ תקשורת ושעה (בגלל הפרש הזמנים).
- לשפר את היעדים ולהגדיר ציפיות משני הצדדים.
- דיון בסדר שבו המודולים יעודכנו.
- מסיימים לערוך את המודולים כך שיתאימו למדריך הסגנון העדכני ביותר של docstrings.
תקופת התיעוד(14 בספטמבר 2020 עד 30 בנובמבר 2020) :
כדאי להגדיר יעדים להשגה בכל שבוע, רצוי להשלים את עדכון המסמכים של מודול אחד או מודול משנה אחד בשבוע או יותר.
בכל המודולים האלה, המטרה העיקרית שלי היא להוסיף קטעים חסרים ולסדר מחדש את מחרוזות ה-docstring כך שיתאימו למדריך הסגנון העדכני. נציג גם את התוצאות השונות שמתקבלות כשמעבירים פרמטרים עם ערכים שונים. כל הפלטות המורכבות יתווספו לקטע 'מלכודות'.
שבוע 1 ( 14 בספטמבר עד 21 בספטמבר) : לי
שבוע 2 (22 בספטמבר עד 29 בספטמבר) : פונקציות : מודולים משניים combinatorics
שבוע 3 (30 בספטמבר עד 6 באוקטובר) : פונקציות
שבוע 4 (7 באוקטובר עד 14 באוקטובר) : Simplify, Crypto
שבוע 5 (15 באוקטובר עד 21 באוקטובר) : דיופנטין
שבוע 6 (22 באוקטובר עד 29 באוקטובר):מודול משנה של :Operations הולונומי
שבוע 7 (30 באוקטובר עד 7 בנובמבר) : מודול אינטגרלים(integrals.integrals), חישוב אינטגרלים באמצעות פונקציות G של Meijer
שבוע 8 (8 בנובמבר עד 15 בנובמבר) : פיזיקה, פונקציות בסוף מודול הקטגוריות, מודול יצירת קוד, מודול משנה מיוחד
שבוע 9 (16 בנובמבר עד 23 בנובמבר) : פיזיקה, פונקציות בסוף מודול הקטגוריות, מודול יצירת קוד, מודול משנה מיוחד
שבוע 10 (24 בנובמבר עד 30 בנובמבר) : הקטע 'מלכודות'
30 בנובמבר עד 5 בדצמבר 2020 בשעה 18:00 (שעון UTC): הגשת פרויקט סופי וכתיבת דוח
3 עד 10 בדצמבר 2020 בשעה 18:00 (שעון UTC): שליחת דיווח על הצלחת הפרויקט ועל הניסיון שלכם בעבודה עם המנטורים
לאחר דיון נוסף עם החונכים, ניתן לשנות את סדר המודולים שהוזכרו כאן.
בהתאם להצעה של המנטורים, אתחיל בעדכון המודולים שקל יותר לעדכן, ואז אמשיך למודולים המורכבים יותר.
למה אני המועמד המתאים לפרויקט הזה?
אני חושב שאני האדם המתאים לפרויקט הזה כי יש לי ניסיון קודם בכתיבת טכנית במדעי המחשב, ואני מנוסה ב-git וב-GitHub.
מאחר ששלחתי יחסי ציבור כדי לעדכן את המסמכים למדריך הסגנון העדכני ביותר ב-Sympy שמוזג בהצלחה, יש לי ביטחון רב עם תהליך העבודה ועם תרומות קבועות.
כשהתחלתי לתרום, נתקלת בכמה שגיאות. סוף סוף התרגלתי להריץ את הבדיקות ולבנות את המסמכים בכל פעם לפני שמבצעים את השינויים, כי זה חשוב מאוד.
אשמח מאוד לתרום לפרויקט הזה.