content/week07/2_Documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/logo.jpg\" style=\"display: block; margin-left: auto; margin-right: auto;\" alt=\"לוגו של מיזם לימוד הפייתון. נחש מצויר בצבעי צהוב וכחול, הנע בין האותיות של שם הקורס: לומדים פייתון. הסלוגן המופיע מעל לשם הקורס הוא מיזם חינמי ללימוד תכנות בעברית.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <span style=\"text-align: right; direction: rtl; float: right;\">תיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">הקדמה</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    אחרי שחיפשתם זמן רב מודולים ואפילו השתמשתם באחד או שניים מהם, הבנתם ודאי את החשיבות הרבה של תיעוד טוב.<br>\n",
    "    בין אם תכתבו קוד כחלק מפרויקט צוותי או שתשחררו מודול בקוד פתוח, איכות התיעוד תקבע אם יהיו לכם לקוחות מרוצים או אם תצטרכו לעמוד מול המון זועם. \n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כמפתחים וכמשתמשים, התיעוד עוזר לנו להבין מהי תכליתם של מודולים, טיפוסים, מחלקות, פעולות ופונקציות.<br>\n",
    "    הוא עוזר לנו להתמצא בקוד ולהבין במהירות אם מה שאנחנו רואים מתאים לנו ומה תהיה צורת השימוש המיטבית בו,<br>\n",
    "    ובכלל, בשפה כמו פייתון, שמקדשת את ערך קְרִיאוּת הקוד, יש ערך גדול מאוד לתיעוד ראוי. \n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    במחברת הקרובה נלמד על תיעוד ראוי בפייתון, על מוסכמות תיעוד ועל גישות שונות לתיעוד.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">הערות ותיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    לפני שנדון לעומק בתיעוד, נדבר מעט על ההבדל שבין הערות בקוד לבין תיעוד בקוד.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    הערות הן שורות מלל המיועדות למפתחים.<br>\n",
    "    הן מכילות מידע אינפורמטיבי על החלטות שקיבלתם בנוגע לקוד. מידע זה נועד לעזור לעמיתיכם לתחזק את הקוד.<br>\n",
    "    הן יופיעו קרוב ככל האפשר שאפשר לקוד שאליו הן מתייחסות, לעיתים אפילו ממש בשורה של הקוד עצמו.<br>\n",
    "    <mark>הערות אמורות להסביר <em>למה</em> דבר מסוים כתוב כמו שהוא כתוב, ולעולם לא <em>מה</em> כתוב בקוד.</mark>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    לעומתן, תיעוד הוא מלל המיועד לאנשים שמשתמשים בקוד שלכם.<br>\n",
    "    הוא יוצמד למודולים, למחלקות, לפעולות ולפונקציות, ויספר בקצרה ובענייניות מה עושה הפונקציה ואיך להשתמש בה.<br>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    אם, לדוגמה, פיתחתם מודול ושיחררתם אותו לאינטרנט,<br>\n",
    "    המשתמשים בו יצפו לתיעוד שברור ממנו איך משתמשים בקוד, ומה קורה בכל אחד ממקרי הקצה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">הערות בקוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">Block Comments</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כפי שאתם ודאי זוכרים מהמחברות שקראתם עד כה, הערה תתחיל בתו <code>#</code> ורווח שיבוא אחריו.<br>\n",
    "    אחרי הסולמית והרווח יבוא המלל שמסביר את ההחלטות שהתקבלו לצורך כתיבת הקוד.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נראה לדוגמה קוד קצר לפירוק מספרים ראשוניים עם הערות שהוטמעו בו:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import math\n",
    "\n",
    "\n",
    "def factorize_prime(number):\n",
    "    while number % 2 == 0: \n",
    "        yield 2\n",
    "        number = number // 2\n",
    "          \n",
    "    # `number` must be odd at this point (we've just factored 2 out).\n",
    "    # Skip even numbers.  Square root is good upper limit, check\n",
    "    # https://math.stackexchange.com/a/1039525 for more info.\n",
    "    divisor = 3\n",
    "    max_divisor = math.ceil(number ** 0.5)\n",
    "    while number != 1 and divisor <= max_divisor: \n",
    "        if number % divisor == 0:\n",
    "            yield divisor\n",
    "            number = number // divisor\n",
    "        else:\n",
    "            divisor += 2\n",
    "              \n",
    "    # If `number` is a prime, just print `number`.\n",
    "    # 1 is not a prime, 2 already taken care of.\n",
    "    if number > 2:\n",
    "        yield number\n",
    "\n",
    "\n",
    "print(list(factorize_prime(5)))\n",
    "print(list(factorize_prime(100)))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בקוד שלמעלה מופיעים שני מקרים של \"<dfn>Block Comment</dfn>\".<br>\n",
    "    מדובר בשורה אחת או יותר של הערה שבאה לפני פיסת קוד, ומטרתה לבאר דברים בקוד.<br>\n",
    "    ה־Block ייכתב באותה רמת הזחה של הקוד שאליו הוא מתייחס, וכל שורה בו תתחיל בתו <code>#</code> שלאחריו יבוא רווח.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נשים לב לנקודות סגנון חשובות, שניכרות היטב בדוגמה האחרונה:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>הערה תמיד תסביר <em>למה</em> עשינו משהו מסוים – ובשום אופן לא <em>מה</em> עשינו.<br>\n",
    "        המתכנת המפורסם ג'ף אטווד <a href=\"https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/\">אומר</a>: \"הקוד יגיד לך מה, ההערות יגידו לך למה\".</li>\n",
    "    <li>הערות מורכבות ממשפטים שלמים שמתחילים באות גדולה ומסתיימים בנקודה.</li>\n",
    "    <li>לעולם לא נשנה שמות של מזהים (משתנים, פונקציות וכו') – גם אם הם מופיעים בתחילת משפט.</li>\n",
    "    <li>הערות חייבות להיכתב באנגלית.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">Inline Comments</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    הערה יכולה להיות ממוקמת גם בסוף שורת הקוד:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Hello World\")  # This is a comment"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    במקרה שבו ההערה נמצאת באותה שורה יחד עם הקוד (כמו בתא האחרון), נהוג לשים לפחות שני רווחים לפני הסימן <code>#</code>.<br>\n",
    "    זוהי צורה מקובלת פחות לכתיבת הערות, כיוון שהיא מאריכה את שורת הקוד, שוברת את רצף הקריאה ולרוב מיותרת.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מתכנתים מתחילים נוטים להסביר מה הקוד עושה, ולשם כך הם משתמשים לעיתים קרובות ב־Inline Comments.<br>\n",
    "    הימנעו מלהסביר מה הקוד שלכם עושה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    דוגמה להערה לא טובה:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snake_y = snake_y % 10  # Take the remainder from 10"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ולעומתה, הערה המתקבלת על הדעת:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "snake_y = snake_y % 10  # Wrap from the bottom if the snake hits the top"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">הוויכוח על הערות</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בעולם התוכנה המקצועי ניטש ויכוח רב שנים על מתי נכון להוסיף הערות לקוד.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    דעה פופולרית אחת דוגלת בריבוי הערות בקוד.<br>\n",
    "    אלו המצדדים בדעה זו מוסיפים לקוד שלהם הערות לצרכים מגוונים:<br>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>הסבר מילולי על פעולת הקוד.</li>\n",
    "    <li>הסבר מדוע קוד מסוים עושה משהו.</li>\n",
    "    <li>הסבר מדוע קוד נראה פגום בצורה מסוימת (לא עוקב אחרי מוסכמות, לא יעיל) ולמה יש להשאיר אותו כך.</li>\n",
    "    <li>הסבר על החלטות שהתקבלו בנוגע לצורת הקוד שנכתב ולארכיטקטורה שלו.</li>\n",
    "    <li>שמירה של קוד לשימוש עתידי (נניח, במקרים של קוד שעוזר לנפות שגיאות).</li>\n",
    "    <li>צירוף נתונים נוספים על אודות הקוד – מהיכן הוא לקוח, תנאי הרישיון שלו וכדומה.</li>\n",
    "    <li>\n",
    "        תיוג, שמטרתו להקל בחיפוש עתידי של בעיות נפוצות בקוד. לדוגמה:\n",
    "        <ul>\n",
    "            <li><code dir=\"ltr\"># FIXME</code> לציון קטע קוד שצריך לתקן.</li>\n",
    "            <li><code dir=\"ltr\"># TODO</code> ואחריו מלל שמסביר משהו שעדיין צריך לבצע ועוד לא נפתר.</li>\n",
    "            <li><code dir=\"ltr\"># HACK</code> לציון מעקף שנועד לפתור בעיה, פעמים רבות בדרך בעייתית.</li>\n",
    "        </ul>\n",
    "    </li>\n",
    "    <li>שחרור קיטור. בקוד המקור של פרויקט הקוד הפתוח <a href=\"https://www.vidarholen.net/contents/wordcount/\">Linux</a>, לדוגמה, מופיעה המילה \"crap\" מעל 150 פעמים, מספר שנמצא במגמת עלייה לאורך השנים.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    דעה פופולרית אחרת דוגלת בצמצום ההערות בקוד למינימום ההכרחי.<br>\n",
    "    אלו המצדדים בדעה זו משתדלים להמעיט ככל האפשר בהוספת הערות לקוד.<br>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">    \n",
    "    טענותיהם של הנמנים עם אסכולת צמצום ההערות מגוונות יחסית:<br>\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>קוד צריך להסביר את עצמו. אם הוספת הערות לקוד, סימן שהקוד לא מובן דיו, וזה מצב שיפגע במפתחי הקוד בעתיד.</li>\n",
    "    <li>הערות שמסבירות קוד יוצרות שכפול – ושכפול בקוד <a href=\"https://en.wikipedia.org/wiki/Don%27t_repeat_yourself\">זה רע</a>.</li>\n",
    "    <li>\n",
    "        הערות מצריכות תחזוקה בפני עצמן – שינוי של קוד יצריך לרוב שינוי של ההערה שמתייחסת אליו.<br>\n",
    "        רוב המפתחים שוכחים לתחזק את ההערות, ולעיתים נשארות הערות שלא תואמות את הקוד עצמו.<br>\n",
    "        הערה שאומרת דבר לא נכון על הקוד גרועה בהרבה מחוסר הערה.\n",
    "    </li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">    \n",
    "    האמת, כרגיל, נמצאת איפשהו באמצע, ולא מתפקידה של מחברת זו להכריע בוויכוח הזה.<br>\n",
    "    כן נזכיר כמה כללים בסיסיים שפחות או יותר מקובלים על כולם:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>השתדלו להימנע מהערות שבבירור אין בהן צורך.</li>\n",
    "    <li>אל תוסיפו הערות על קוד לא טוב דיו – במקום זאת, שפרו אותו.</li>\n",
    "    <li>ודאו תמיד שההערות שלכם תואמות לקוד שכתבתם.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מחרוזות תיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ניזכר בפונקציה <var>help</var>, שמטרתה להציג לנו תיעוד בנוגע לערך מסוים בתוכנית:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "quote = \"So many books, so little time.\"\n",
    "help(quote.upper)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    והיא תעבוד היטב, לשמחתנו, גם עבור סוג המשתנה <var>str</var> עצמו, אם כי בצורה טיפה פחות חיננית (פנו ערב כדי לקרוא את זה):\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "quote = \"So many books, so little time.\"\n",
    "help(str)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    אם ננסה להגדיר פונקציה משלנו, העברתה כארגומנט לפונקציה <var>help</var> תחזיר לנו מידע לא מועיל בעליל: \n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    return a + b\n",
    "\n",
    "\n",
    "help(add)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    אז מה עלינו לעשות כדי להוסיף תיעוד?<br>\n",
    "    מתברר שזה לא כזה מסובך. בסך הכול צריך להוסיף משהו שנקרא \"מחרוזת תיעוד\".\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מחרוזות תיעוד של שורה אחת</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נוסיף לפונקציה שלנו מחרוזת תיעוד של שורה אחת (<dfn>One-line Docstring</dfn>) בצורה הבאה:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    \"\"\"Return the result of a + b.\"\"\"\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בדוגמה האחרונה הוספנו לשורה הראשונה של גוף הפונקציה <dfn>מחרוזת תיעוד</dfn> (<dfn>Docstring</dfn>), שמתחילה ומסתיימת ב־3 מירכאות כפולות.<br>\n",
    "    אפשר להשתמש בסוג מירכאות אחר, אך 3 מירכאות <a href=\"https://www.python.org/dev/peps/pep-0257/#specification\">זו המוסכמה</a> ואנחנו נדבוק בה.<br>\n",
    "    בין המירכאות תיארנו בקצרה מה הפונקציה עושה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כעת הפונקציה <var>help</var> תשתף איתנו פעולה, ונוכל לקבל את התיעוד על הפונקציה שכתבנו: \n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(add)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נקודות חשובות בהקשר זה:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>תיעוד של שורה אחת מיועד עבור מקרים ברורים במיוחד, כמו הפונקציה <var>add</var> שכתבנו.</li>\n",
    "    <li>התיעוד ייכתב בשורה אחת, צמוד למירכאות, ללא שורות ריקות לפניו או אחריו.</li>\n",
    "    <li>התיעוד ינוסח בצורת פקודה ולא כסיפור (\"החזר את התוצאה\" ולא \"הפונקציה מחזירה...\").<br>\n",
    "        כלל אצבע טוב הוא לשמור על הצורה \"עשה X, החזר Y\" <span div=\"ltr\">(באנגלית: Do X, Return Y)</span>.</li>\n",
    "    <li>תיעוד של שורה אחת לא יכלול את סוג הפרמטרים (a או b, במקרה שלנו). הוא יכול לכלול את הסוג של ערך ההחזרה.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מחרוזות תיעוד מרובות שורות</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ניקח לדוגמה פונקציה שמקבלת נתיב ומחזירה את חלקיו:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_parts(path):\n",
    "    current_part = \"\"\n",
    "    for char in self.fullpath:\n",
    "        if char in r\"\\/\":\n",
    "            yield current_part\n",
    "            current_part = \"\"\n",
    "        else:\n",
    "            current_part = current_part + char\n",
    "    if current_part != \"\":\n",
    "        yield current_part"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בתור התחלה, נוסיף לפונקציה מחרוזת תיעוד של שורה אחת שמתארת בקצרה מה תכליתה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_parts(path):\n",
    "    \"\"\"Split the path, return each part separately.\"\"\"\n",
    "    current_part = \"\"\n",
    "    for char in self.fullpath:\n",
    "        if char in r\"\\/\":\n",
    "            yield current_part\n",
    "            current_part = \"\"\n",
    "        else:\n",
    "            current_part = current_part + char\n",
    "    if current_part != \"\":\n",
    "        yield current_part"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כדי להפוך את התיעוד למרובה שורות, נוסיף שורה ריקה אחרי השורה שמתארת בקצרה מה עושה הפונקציה.<br>\n",
    "    אחרי השורה הריקה נוסיף תיאור כללי יותר שמסביר מה אפשר לצפות שהפונקציה תחזיר, ומה הפרמטרים שהיא מצפה לקבל.<br>\n",
    "    המירכאות הסוגרות יזכו בשורה משלהן:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_parts(path):\n",
    "    \"\"\"Split the path, return each part separately.\n",
    "\n",
    "    Each \"part\" of the path can be defined as a drive, folder, or\n",
    "    file, separated by a forward slash (/, typically used in Linux/Mac)\n",
    "    or by a backslash (usually used in Windows).\n",
    "    \n",
    "    path -- String that consists of a drive (if applicable), folders\n",
    "            and files, separated by a forward slash or by a backslash.\n",
    "    \"\"\"\n",
    "    current_part = \"\"\n",
    "    for char in self.fullpath:\n",
    "        if char in r\"\\/\":\n",
    "            yield current_part\n",
    "            current_part = \"\"\n",
    "        else:\n",
    "            current_part = current_part + char\n",
    "    if current_part != \"\":\n",
    "        yield current_part"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    סוג כזה של תיעוד נקרא \"<dfn>מחרוזת תיעוד מרובת שורות</dfn>\" (<dfn>Multi-line Docstring</dfn>).<br>\n",
    "    נכתוב אותו כדי לעזור למי שישתמש בפונקציה להבין מה מטרתה, אילו פרמטרים היא מצפה לקבל ואילו ערכים יוחזרו ממנה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    היכן נשתמש בתיעוד מרובה שורות?\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>בראש הקוד – נסכם מה מטרת הקוד, ונסביר בקצרה מה הוא כולל.</li>\n",
    "    <li>בראש מחלקה – נסכם את התנהגות המחלקה ונתעד את הפעולה <code>__init__</code>.</li>\n",
    "    <li>בפונקציה או בפעולה – נסכם:\n",
    "        <ul>\n",
    "            <li>מה מטרתה.</li>\n",
    "            <li>אילו ארגומנטים היא מצפה לקבל.</li>\n",
    "            <li>מהם ערכי ההחזרה שלה.</li>\n",
    "            <li>אילו שגיאות היא עלולה להחזיר.</li>\n",
    "            <li>על מה היא משפיעה חוץ מאשר על המשתנים בפונקציה עצמה (נניח – כתיבה לקובץ).</li>\n",
    "        </ul>\n",
    "    </li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">דוגמה לתיעוד בסיסי</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"A demonstration of writing well documented Python code.\n",
    "\n",
    "This snippet demonstrates how a well documented code should look.\n",
    "Each method and class is documented, and there is also\n",
    "documentation for the script itself.\n",
    "\"\"\"\n",
    "import os\n",
    "\n",
    "\n",
    "class Path:\n",
    "    \"\"\"Represent a filesystem path.\n",
    "    \n",
    "    It is used to simplify the work with paths across different\n",
    "    operating systems. The initialization method takes a string and\n",
    "    populates the full path property along with \"parts,\" which is a\n",
    "    version of the path after we split it using path separator\n",
    "    characters.\n",
    "\n",
    "    Basic Usage:\n",
    "\n",
    "    >>> Path(r'C:\\Yossi').get_drive_letter()\n",
    "    'C:'\n",
    "    >>> str(Path(r'C:\\Messed/Up/Path\\To\\file.png'))\n",
    "    'C:/Messed/Up/Path/To/file.png'\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, path):\n",
    "        self.fullpath = path\n",
    "        self.parts = list(self.get_parts())\n",
    "\n",
    "    def get_parts(self):\n",
    "        \"\"\"Split the path, return each part separately.\n",
    "\n",
    "        Each \"part\" of the path can be defined as a drive, folder, or\n",
    "        file, separated by a forward slash (/, typically used in\n",
    "        Linux/Mac) or by a backslash (usually used in Windows).\n",
    "\n",
    "        path -- String that consists of a drive (if applicable),\n",
    "                folders, and files, separated by a forward slash or by\n",
    "                a backslash.\n",
    "        \"\"\"\n",
    "        current_part = \"\"\n",
    "        for char in self.fullpath:\n",
    "            if char in r\"\\/\":\n",
    "                yield current_part\n",
    "                current_part = \"\"\n",
    "            else:\n",
    "                current_part = current_part + char\n",
    "        if current_part != \"\":\n",
    "            yield current_part\n",
    "\n",
    "    def get_drive_letter(self):\n",
    "        \"\"\"Return the drive letter of the path, when applicable.\"\"\"\n",
    "        return self.parts[0].rstrip(\":\")\n",
    "\n",
    "    def get_dirname(self):\n",
    "        \"\"\"Return the full path without the last part.\"\"\"\n",
    "        path = \"/\".join(self.parts[:-1])\n",
    "        return Path(path)\n",
    "\n",
    "    def get_basename(self):\n",
    "        \"\"\"Return the last part of the path.\"\"\"\n",
    "        return self.parts[-1]\n",
    "\n",
    "    def get_extension(self):\n",
    "        \"\"\"Return the extension of the filename.\n",
    "        \n",
    "        If there is no extension, return an empty string.\n",
    "        This does not include the leading period.\n",
    "        For example: 'txt'\n",
    "        \"\"\"\n",
    "        name = self.get_basename()\n",
    "        i = name.rfind('.')\n",
    "        if 0 < i < len(name) - 1:\n",
    "            return name[i + 1:]\n",
    "        return ''\n",
    "\n",
    "\n",
    "    def is_exists(self):\n",
    "        \"\"\"Check if the path exists, return boolean value.\"\"\"\n",
    "        return os.path.exists(str(self))\n",
    "\n",
    "    def normalize_path(self):\n",
    "        \"\"\"Create a normalized string of the path for printing.\"\"\"\n",
    "        normalized = \"\\\\\".join(self.parts)\n",
    "        return normalized.rstrip(\"\\\\\")\n",
    "\n",
    "    def info_message(self):\n",
    "        \"\"\"Return a long string with essential details about the file.\n",
    "        \n",
    "        The string contains:\n",
    "        - Normalized path\n",
    "        - Drive letter\n",
    "        - Dirname\n",
    "        - Basename\n",
    "        - File extension (displayed even if not applicable)\n",
    "        - If the file exists\n",
    "        \n",
    "        Should be used to easily print the details about the path.\n",
    "        \"\"\"\n",
    "        return f\"\"\"\n",
    "            Some info about \"{self}\":\n",
    "            Drive letter: {self.get_drive_letter()}\n",
    "            Dirname: {self.get_dirname()}\n",
    "            Last part of path: {self.get_basename()}\n",
    "            File extension: {self.get_extension()}\n",
    "            Is exists?: {self.is_exists()}\n",
    "        \"\"\".strip()\n",
    "\n",
    "    def __str__(self):\n",
    "        return self.normalize_path()\n",
    "\n",
    "\n",
    "EXAMPLES = (\n",
    "    r\"C:\\Users\\Yam\\python.jpg\",\n",
    "    r\"C:/Users/Yam/python.jpg\",\n",
    "    r\"C:\",\n",
    "    r\"C:\\\\\",\n",
    "    r\"C:/\",\n",
    "    r\"C:\\Users/\",\n",
    "    r\"D:/Users/\",\n",
    "    r\"C:/Users\",\n",
    ")\n",
    "for example in EXAMPLES:\n",
    "    path = Path(example)\n",
    "    print(path.info_message())\n",
    "    print()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מאחורי הקלעים</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כאשר אנחנו מוסיפים לישות מסוימת מחרוזת תיעוד, נוספת לה תכונת קסם בשם <code>__doc__</code> שמכילה את התיעוד שלה.<br>\n",
    "    התוכן של התכונה הזו הוא זה שמודפס כאשר אנחנו מפעילים את הפונקציה <var>help</var>.<br>\n",
    "    נבחן לדוגמה את תוכן התכונה <code>__doc__</code> של <var>quote.upper</var> שסקרנו בתחילת המחברת.<br>\n",
    "    אפשר לראות שהיא זהה לחלוטין למחרוזת שקיבלנו כשהפעלנו עליה <var>help</var>:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "help(quote.upper)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(quote.upper.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ומה קורה כשניצור פונקציה משלנו?<br>\n",
    "    ננסה ליצור לדוגמה את ידידתנו הוותיקה, הפונקציה <var>add</var>:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    return a + b"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    כיוון שלא הוספנו לפונקציה תיעוד, התכונה <code>__doc__</code> תוגדר כ־<code>None</code>:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(add.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נוסיף תיעוד ונראה את השינוי:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def add(a, b):\n",
    "    \"\"\"Return the result of a + b.\"\"\"\n",
    "    return a + b\n",
    "\n",
    "print(add.__doc__)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מדובר בידע כללי מגניב, אבל כאנשים מתורבתים לעולם לא נבצע השמה ישירה ל־<code dir=\"ltr\">__doc__</code> ולא ניגש אליה ישירות.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">התפתחות התיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    עם הזמן ראתה קהילת המפתחים בפייתון כי טוב, וחשבה על דרך נעימה ונוחה יותר לקרוא תיעוד ולכתוב אותו.<br>\n",
    "    כיוון שתיעוד הוא חלק חשוב בקוד, התפתחו במרוצת השנים טכנולוגיות ותקנים שמטרתם לסייע למפתחי פייתון לתעד טוב יותר את הקוד שלהם.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">שפת סימון לתיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    תחילה, קהילת פייתון חיפשה דרך לכתוב משהו שהוא יותר מ\"סתם מלל\".<br>\n",
    "    לעיתים קרובות נרצה להדגיש דברים בתיעוד, לתת קישור למקור חיצוני, להוסיף כותרת או לציין פריטים ברשימה.<br>\n",
    "    שפת הסימון המוכרת HTML שמשומשת תדיר ליצירת דפי אינטרנט הייתה כבר קיימת, אבל בפייתון חיפשו שפה נקייה יותר שנוח לעין לסרוק.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    לצורך כך פותחה בשנת 2002 שפת הסימון <dfn>reStructuredText</dfn> (או בקיצור – <dfn>reST</dfn>), שמאפשרת להפוך מלל שאנחנו כותבים לטקסט מסוגנן.<br>\n",
    "    מטרתה העיקרית של reST הייתה לאפשר הכנסת טקסט מסוגנן לתיעוד טכני בפייתון, ופייתון אכן אימצה אותה רשמית לצורך זה.<br>\n",
    "    היא מאפשרת לכתוב לא רק תיעוד בקוד, אלא גם תיעוד מילולי כללי על מטרותיו של הפרויקט ועל דרך השימוש בו (כמו ספר תיעוד קטן).\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    קצרה היריעה מלכלול פה הדרכה על שימוש ב־reStructuredText, אבל אנחנו ממליצים בחום לקרוא את המדריך המקוצר שנמצא <a href=\"https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html\">כאן</a>.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מלל שנכתב ב־reStructuredText ייראה כך עבור מי שכתב אותו:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<pre style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "אפשר לראות בטקסט *הזה* טעימה קטנה מהיכולות של **reStructuredText**.\n",
    "חלק מהאפשרויות הפחות מתוחכמות שלו כוללות:\n",
    "\n",
    "* הדגשה, מלל מוטה וקו תחתון.\n",
    "* רשימות.\n",
    "* סימון של קוד, כמו `print(\"Hello World\")`.\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    וייראה כך בתוצאה הסופית:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "אפשר לראות בטקסט <em>הזה</em> טעימה קטנה מהיכולות של <strong>reStructuredText</strong>.<br>\n",
    "חלק מהאפשרויות הפחות מתוחכמות שלו כוללות:\n",
    "</p>\n",
    "\n",
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>הדגשה, מלל מוטה וקו תחתון.</li>\n",
    "    <li>רשימות.</li>\n",
    "    <li>סימון של קוד, כמו <code dir=\"ltr\">print(\"Hello World\")</code>.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מנוע ליצירת קובצי תיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בשנת 2008 פותח בקהילת הפייתון כלי בשם <dfn>Sphinx</dfn>.<br>\n",
    "    מטרתו לסרוק את התיעוד של פרויקט הקוד שלכם, וליצור ממנו מסמך תיעוד שנעים לקרוא ב־PDF או ב־HTML.<br>\n",
    "    Sphinx, כמובן, תומך במסמכים שנכתבו ב־reStructuredText, והוא הפך במהרה לפופולרי מאוד.<br>\n",
    "    אתר התיעוד הנוכחי של פייתון נוצר באמצעותו.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בהמשך הקורס נכתוב פרויקטים, ובהם נוכל להשתמש ב־Sphinx ליצירת מסמכים שיעזרו למשתמשים בפרויקט להתמצא בו.<br>\n",
    "    משתמשים בולטים ב־Sphinx כוללים, <a href=\"https://www.sphinx-doc.org/en/master/examples.html\">בין השאר</a>, את:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li><a href=\"https://docs.python.org/3/\">אתר התיעוד הרשמי של פייתון</a>.</li>\n",
    "    <li>המודול הפופולרי לניהול ולניתוח מידע <a href=\"https://pandas.pydata.org/pandas-docs/stable/reference/\">pandas</a>.</li>\n",
    "    <li>המודול הפופולרי לעיבוד דפי אינטרנט <a href=\"https://www.crummy.com/software/BeautifulSoup/bs4/doc/\">BeautifulSoup</a>.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">אתר לאחסון קובצי תיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בשנת 2010 פותח אתר בשם Read the Docs, שמטרתו לרכז תיעוד לפרויקטים שנכתבו בפייתון.<br>\n",
    "    האתר מאפשר להעלות לרשת בקלות תיעודים שנוצרו בעזרת Sphinx ולהנגיש אותם לקהל הרחב.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    משתמשים בולטים ב־Read the Docs כוללים, בין השאר, את:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>המודול הפופולרי לעיבוד ולשליחה של בקשות אינטרנט <a href=\"https://requests.readthedocs.io/en/master/\">requests</a>.</li>\n",
    "    <li>מנהל החבילות של פייתון <a href=\"https://pip.pypa.io/en/stable/\">pip</a>.</li>\n",
    "    <li>פלטפורמת המחברות <a href=\"https://jupyter-notebook.readthedocs.io/en/stable/\">Jupyter Notebooks</a>.</li>\n",
    "    <li>המודול הנפוץ ביותר לעבודה עם כלים מתמטיים <a href=\"https://numpydoc.readthedocs.io/en/latest/\">NumPy</a>.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">סגנונות תיעוד</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    במשך שנים חיפשו מפתחי פייתון דרך אחידה יותר לכתוב מחרוזות תיעוד.<br>\n",
    "    בכלל, מתכנתים אוהבים שלדברים יש צורה מוסכמת ומוגדרת מראש.<br> \n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    בעקבות הצורך הזה, התחילו להתפתח סגנונות שמגדירים בצורה הדוקה יותר כיצד אמור להיראות התוכן של מחרוזת תיעוד.<br>\n",
    "    למה זה טוב, אתם שואלים? כי כשלדברים יש תקן אחיד אפשר לעשות הרבה דברים מגניבים:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>אפשר לבנות מנוע חיפוש עבור תיעודי מודולים.</li>\n",
    "    <li>אפשר להפעיל כלים כמו Sphinx, שיסרקו את המודול ויצרו מהתיעוד שיש בו אתר תיעוד – באופן אוטומטי!</li>\n",
    "    <li>אפשר להפסיק לבזבז זמן מיותר בוויכוחים אינטרנטיים על איך יפה יותר לכתוב 😜</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מובן שכמפתחים לא באמת הצלחנו לוותר על הוויכוחים האינטרנטיים, ולכן הנקודה האחרונה לא תקפה.<br>\n",
    "    עם הזמן התגבשו שלושה סגנונות פופולריים ל\"איך אמורה להראות מחוזת תיעוד\".\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    נבחן את ההבדלים בין הסגנונות, ונשאיר לכם לבחור באיזה סגנון תעדיפו להשתמש.<br>\n",
    "    לפניכם קוד נחמד וקצרצר שאנחנו הולכים לתעד בשארית המחברת, בכל אחד מהסגנונות הללו.<br>\n",
    "    בקוד נגדיר מחלקה של סניף דואר, שתאפשר למשתמשים בה לשלוח הודעות זה לזה.<br>\n",
    "    ללא תיעוד כלל, המחלקה תיראה כך:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostOffice:\n",
    "    def __init__(self, usernames):\n",
    "        self.message_id = 0\n",
    "        self.boxes = {user: [] for user in usernames}\n",
    "        \n",
    "    def send_message(self, sender, recipient, message_body, urgent=False):\n",
    "        user_box = self.boxes[recipient]\n",
    "        self.message_id = self.message_id + 1\n",
    "        message_details = {\n",
    "            'id': self.message_id,\n",
    "            'body': message_body,\n",
    "            'sender': sender,\n",
    "        }\n",
    "        if urgent:\n",
    "            user_box.insert(0, message_details)\n",
    "        else:\n",
    "            user_box.append(message_details)\n",
    "        return self.message_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    וכך תיראה דוגמה לפונקציה מתועדת שמדגימה כיצד המחלקה עובדת:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def show_example():\n",
    "    \"\"\"Show example of using the PostOffice class.\"\"\"\n",
    "    users = ('Newman', 'Mr. Peanutbutter')\n",
    "    post_office = PostOffice(users)\n",
    "    message_id = post_office.send_message(\n",
    "        sender='Mr. Peanutbutter',\n",
    "        recipient='Newman',\n",
    "        message_body='Hello, Newman.',\n",
    "    )\n",
    "    print(f\"Successfuly sent message number {message_id}.\")\n",
    "    print(post_office.boxes['Newman'])\n",
    "\n",
    "\n",
    "show_example()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מבולבלים? איזה מזל שאנחנו הולכים לתעד את המחלקה הזו.<br>\n",
    "    קדימה, לעבודה.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">Google Docstrings</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    גוגל מתחזקים זה שנים רבות <a href=\"https://google.github.io/styleguide/pyguide.html\">מסמך מוסכמות</a> ארוך משלהם שמפרט את סגנון הכתיבה הפנימי הרצוי בפייתון בחברה.<br>\n",
    "    במסמך, בין היתר, <a href=\"https://google.github.io/styleguide/pyguide.html#383-functions-and-methods\">מתארים גוגל</a> כיצד הם מאמינים שצריכות להיראות מחרוזות תיעוד.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    תוכלו לראות דוגמה לאופן שבו אמורות להיראות מחרוזות התיעוד של Google <a href=\"https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html\">כאן</a>.<br>\n",
    "    נראה דוגמה לתיעוד המחלקה <var>PostOffice</var> ופעולותיה בשיטה של גוגל, ומייד אחר כך ננתח מה ראינו.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostOffice:\n",
    "    \"\"\"A Post Office class. Allows users to message each other.\n",
    "    \n",
    "    Args:\n",
    "        usernames (list): Users for which we should create PO Boxes.\n",
    "\n",
    "    Attributes:\n",
    "        message_id (int): Incremental id of the last message sent.\n",
    "        boxes (dict): Users' inboxes.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, usernames):\n",
    "        self.message_id = 0\n",
    "        self.boxes = {user: [] for user in usernames}\n",
    "        \n",
    "    def send_message(self, sender, recipient, message_body, urgent=False):\n",
    "        \"\"\"Send a message to a recipient.\n",
    "\n",
    "        Args:\n",
    "            sender (str): The message sender's username.\n",
    "            recipient (str): The message recipient's username.\n",
    "            message_body (str): The body of the message.\n",
    "            urgent (bool, optional): The urgency of the message.\n",
    "                                    Urgent messages appear first.\n",
    "\n",
    "        Returns:\n",
    "            int: The message ID, auto incremented number.\n",
    "\n",
    "        Raises:\n",
    "            KeyError: If the recipient does not exist.\n",
    "\n",
    "        Examples:\n",
    "            After creating a PO box and sending a letter,\n",
    "            the recipient should have 1 message in the\n",
    "            inbox.\n",
    "\n",
    "            >>> po_box = PostOffice(['a', 'b'])\n",
    "            >>> message_id = po_box.send_message('a', 'b', 'Hello!')\n",
    "            >>> len(po_box.boxes['b'])\n",
    "            1\n",
    "            >>> message_id\n",
    "            1\n",
    "        \"\"\"\n",
    "        user_box = self.boxes[recipient]\n",
    "        self.message_id = self.message_id + 1\n",
    "        message_details = {\n",
    "            'id': self.message_id,\n",
    "            'body': message_body,\n",
    "            'sender': sender,\n",
    "        }\n",
    "        if urgent:\n",
    "            user_box.insert(0, message_details)\n",
    "        else:\n",
    "            user_box.append(message_details)\n",
    "        return self.message_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    לפי מסמך הסגנון של גוגל, לפעולה צריכים להיות 3 חלקי תיעוד:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li><em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Args:</em> – רשימת הארגומנטים שהיא הולכת לקבל, סוגם והסבר קצר על כל אחד מהם.</li>\n",
    "    <li><em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Returns:</em> – הערך שהפונקציה מחזירה והסוג שלו. במקרה של generator החלק יקרא <em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Yields :</em> במקום.</li>\n",
    "    <li><em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Raises:</em> – השגיאות שהפונקציה עלולה לזרוק ובאילו מקרים זה עלול לקרות.</li>\n",
    "    <li>אפשר להוסיף גם חלקים משלנו, כמו <em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Examples:</em> שיראה כיצד הפונקציה פועלת. מומלץ לא להגזים עם זה.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    יש לתעד גם מחלקות כמובן:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li><em dir=\"ltr\" style=\"border-style: 1px solid; padding: 0 0.5em;\">Attributes:</em> – התכונות של המופעים שייווצרו על ידי המחלקה.</li>\n",
    "    <li>כל חלקי התיעוד ששייכים לפעולה רגילה, בהתייחס לפעולת ה־<code>__init__</code> של המחלקה.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">NumPy Docstrings</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    NumPy היא המודול המוביל בפייתון בכל הקשור לכלים מתמטיים.<br>\n",
    "    שיטת התיעוד שלו די דומה לזו של גוגל, ומתועדת <a href=\"https://numpydoc.readthedocs.io/en/latest/format.html\">כאן</a>.<br>\n",
    "    היא מעט קריאה יותר לעין אנושית, אך משתמשת ביותר שטח לאורך הדף:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostOffice:\n",
    "    \"\"\"A Post Office class. Allows users to message each other.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    usernames : list\n",
    "        Users for which we should create PO Boxes.\n",
    "\n",
    "    Attributes\n",
    "    ----------\n",
    "    message_id : int\n",
    "        Incremental id of the last message sent.\n",
    "    boxes : dict\n",
    "        Users' inboxes.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, usernames):\n",
    "        self.message_id = 0\n",
    "        self.boxes = {user: [] for user in usernames}\n",
    "        \n",
    "    def send_message(self, sender, recipient, message_body, urgent=False):\n",
    "        \"\"\"Send a message to a recipient.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        sender : str\n",
    "            The message sender's username.\n",
    "        recipient : str\n",
    "            The message recipient's username.\n",
    "        message_body : str\n",
    "            The body of the message.\n",
    "        urgent : bool, optional\n",
    "            The urgency of the message.\n",
    "            Urgent messages appear first.\n",
    "\n",
    "        Returns\n",
    "        -------\n",
    "        int\n",
    "            The message ID, auto incremented number.\n",
    "\n",
    "        Raises\n",
    "        ------\n",
    "        KeyError\n",
    "            If the recipient does not exist.\n",
    "\n",
    "        Examples\n",
    "        --------\n",
    "        After creating a PO box and sending a letter,\n",
    "        the recipient should have 1 messege in the\n",
    "        inbox.\n",
    "\n",
    "        >>> po_box = PostOffice(['a', 'b'])\n",
    "        >>> message_id = po_box.send_message('a', 'b', 'Hello!')\n",
    "        >>> len(po_box.boxes['b'])\n",
    "        1\n",
    "        >>> message_id\n",
    "        1\n",
    "        \"\"\"\n",
    "        user_box = self.boxes[recipient]\n",
    "        self.message_id = self.message_id + 1\n",
    "        message_details = {\n",
    "            'id': self.message_id,\n",
    "            'body': message_body,\n",
    "            'sender': sender,\n",
    "        }\n",
    "        if urgent:\n",
    "            user_box.insert(0, message_details)\n",
    "        else:\n",
    "            user_box.append(message_details)\n",
    "        return self.message_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">Sphinx</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    מעבר להיותו כלי ליצירת מסמכי תיעוד, ב־Sphinx קיימת גם הגדרה לצורה שבה לדעתם מחרוזות תיעוד אמורות להיראות.<br>\n",
    "    בלי לחץ – Sphinx ידע להמיר את התיעוד שלכם למסמך גם אם תשתמשו ב־Google Docstrings או ב־NumPy Docstrings.<br>\n",
    "    סגנון זה תופס את השטח המזערי ביותר לאורך הדף, אך הוא מעט קשה יותר לקריאה.<br>\n",
    "    מחרוזות התיעוד ש־Sphinx מגדירים נראות כך:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "class PostOffice:\n",
    "    \"\"\"A Post Office class. Allows users to message each other.\n",
    "\n",
    "    :ivar int message_id: Incremental id of the last message sent.\n",
    "    :ivar dict boxes: Users' inboxes.\n",
    "\n",
    "    :param list usernames: Users for which we should create PO Boxes.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, usernames):\n",
    "        self.message_id = 0\n",
    "        self.boxes = {user: [] for user in usernames}\n",
    "        \n",
    "    def send_message(self, sender, recipient, message_body, urgent=False):\n",
    "        \"\"\"Send a message to a recipient.\n",
    "\n",
    "        :param str sender: The message sender's username.\n",
    "        :param str recipient: The message recipient's username.\n",
    "        :param str message_body: The body of the message.\n",
    "        :param urgent: The urgency of the message.\n",
    "        :type urgent: bool, optional\n",
    "        :return: The message ID, auto incremented number.\n",
    "        :rtype: int\n",
    "        :raises KeyError: if the recipient does not exist.\n",
    "        \"\"\"\n",
    "        user_box = self.boxes[recipient]\n",
    "        self.message_id = self.message_id + 1\n",
    "        message_details = {\n",
    "            'id': self.message_id,\n",
    "            'body': message_body,\n",
    "            'sender': sender,\n",
    "        }\n",
    "        if urgent:\n",
    "            user_box.insert(0, message_details)\n",
    "        else:\n",
    "            user_box.append(message_details)\n",
    "        return self.message_id"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">לסיכום</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    למדנו על ההבדל בין הערות לבין תיעוד, על הגישות השונות אליהם ומתי להשתמש בכל אחד מהם.<br>\n",
    "    סקרנו קצת את התפתחות רעיון התיעוד לאורך השנים בפייתון, ואת הכלים המשמשים את הקהילה בתהליך יצירת התיעוד.<br>\n",
    "    למדנו גם על סגנונות תיעוד פופולריים, שיאפשרו לכם לכתוב תיעוד קריא בקוד שלכם, ובעתיד גם ליצור מסמכי תיעוד בעצמכם.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">מונחים</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<dl style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <dt>הערה (Comment)</dt>\n",
    "    <dd>\n",
    "        קטע מילולי המשובץ בקוד ומתייחס אליו, ומטרתו להסביר, לבאר או להפנות את תשומת הלב של מתכנתים אחרים לנקודה מסוימת.<br>\n",
    "        ההערה יכולה להופיע בסוף שורת קוד, בשורה עצמאית או כרצף של כמה שורות זו אחרי זו.<br>\n",
    "        כתיבת הערות הסבר עבור קוד לא מובן נחשבת בעיני רבים לרעיון רע, ולכן במקרה כזה עדיף פשוט לשפר את הקוד.\n",
    "    </dd>\n",
    "    <dt>תיעוד (Documentation)</dt>\n",
    "    <dd>\n",
    "        אוסף הנחיות עבור משתמשי הקוד.<br>\n",
    "        התיעוד יעזור למשתמש חיצוני להבין כיצד מתנהגת כל ישות בקוד, מה היא מצפה לקבל ומה היא עשויה להחזיר.<br>\n",
    "        ראוי שכל ישות בקוד תהיה מתועדת היטב.\n",
    "    </dd>\n",
    "    <dt>מחרוזת תיעוד (Docstring)</dt>\n",
    "    <dd>\n",
    "        מחרוזת המוצבת בשורה הראשונה של פונקציה, פעולה, מחלקה או מודול ומטרתה לתאר את התפקיד של אותה ישות.<br>\n",
    "        היא יכולה להיכתב בשורה אחת או בשורות רבות, והיא מתארת את תכלית הקוד ואת דרכי השימוש בו.<br>\n",
    "        בניגוד להערה רגילה, מחרוזות תיעוד מתארות ממש מה הפונקציה עושה, ולא למה.<br>\n",
    "        לעיתים מחרוזות התיעוד יכללו דוגמאות של ממש לשימוש בקוד.\n",
    "    </dd>\n",
    "    <dt>reStructuredText</dt>\n",
    "    <dd>\n",
    "        שפת סימון שנוצרה ב־2002 במטרה להקל על כותבי תיעוד ומסמכים טכניים.<br>\n",
    "        מטרת השפה היא לייצר תסדיר שנוח לקרוא בעין אנושית, ושיהיה אפשר ליצור ממנו אוטומטית מסמכים מסוגננים.<br>\n",
    "        שפת הסימון הזו תוקננה כשפת הסימון הרשמית שבה כותבים מסמכי תיעוד בפייתון.\n",
    "    </dd>\n",
    "    <dt>Sphinx</dt>\n",
    "    <dd>\n",
    "        כלי שמטרתו לעזור לייצר מסמכי דוקומנטציה.<br>\n",
    "        כיום הוא הכלי הפופולרי ביותר לצורך הזה בעולם הפייתון, בפער ניכר מכלים דומים.<br>\n",
    "        Sphinx גם יצרו סגנון תיעוד פופולרי (ע\"ע \"סגנון תיעוד\").\n",
    "    </dd>\n",
    "    <dt>Read the Docs</dt>\n",
    "    <dd>\n",
    "        אתר המאפשר למשתמשים להעלות אליו מסמכי תיעוד.<br>\n",
    "    </dd>\n",
    "    <dt>סגנון תיעוד</dt>\n",
    "    <dd>\n",
    "        ידוע בשמות: Documentation Style, Documentation Format, Docstring Format, Docstring Style.<br>\n",
    "        צורה מקובלת לכתיבת תיעוד ולפירוט התכונות של פונקציה, פעולה, מחלקה או מודול.<br>\n",
    "        שלושת הסגנונות הנפוצים ביותר הם של Sphinx, של Google ושל NumPy.\n",
    "    </dd>\n",
    "</dl>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">תרגילים</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">צָב שָׁלוּחַ</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ממשו שתי פעולות נוספות למחלקת <var>PostOffice</var>:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li>הפעולה <var>read_inbox</var> תקבל כפרמטרים את שם המשתמש ואת מספר ההודעות שהוא מעוניין לקרוא (נקרא לה $N$).<br>\n",
    "        היא תחזיר את $N$ ההודעות הראשונות בתיבת הדואר הנכנס של המשתמש.<br>\n",
    "        אם לא הועבר מספר הודעות, החזירו את כל ההודעות בתיבת הדואר הנכנס של המשתמש.<br>\n",
    "        ההודעות יסומנו כנקראו ולא יוחזרו למשתמש בקריאה הבאה.\n",
    "    </li>\n",
    "    <li>הפעולה <var>search_inbox</var> תקבל כפרמטרים שם משתמש ומחרוזת.<br>\n",
    "        היא תחזיר כרשימה את כל ההודעות שמכילות את המחרוזת, בכותרת שלהן או בגופן.<br>\n",
    "    </li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    חלק ממטרת התרגיל היא תרגול היכולת שלכם להיכנס לקוד קיים.<br>\n",
    "    נסו לשנות את הקוד הקיים במידה, והסבירו את השינויים שלכם אם לדעתכם עולה צורך כזה.<br>\n",
    "    ודאו שהקוד שלכם מתועד היטב.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### <span style=\"text-align: right; direction: rtl; float: right; clear: both;\">אורטל קומבט – חלק 1</span>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    ממשו מחלקה בשם Player שיודעת לקבל שם שחקן, וליצור שחקן חדש.<br>\n",
    "    לכל שחקן יש לפחות את התכונות הבאות:\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<ul style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    <li><var>name</var> – שם השחקן.</li>\n",
    "    <li><var>hp</var> – חיים (ערך מספרי שלם) שמאותחלים לערך המספרי 100.</li>\n",
    "    <li><var>exp</var> – נקודות ניסיון (ערך מספרי שלם) שמאותחלות לערך המספרי 0.</li>\n",
    "    <li><var>level</var> – רמת השחקן (ערך מספרי שלם) שמאותחלת לערך המספרי 1. לצורך תרגיל זה רמת השחקן תהיה תמיד 1.</li>\n",
    "    <li><var>nemeses</var> – רשימת אויבים.</li>\n",
    "    <li>פעולת \"<var>attack</var>\" – שמקבלת מופע של שחקן, ומורידה לו בין <span dir=\"ltr\">$L \\cdot 5$</span> ל־<span dir=\"ltr\">$L \\cdot 20$</span>  חיים (הגרילו), כאשר $L$ מייצגת את רמת השחקן המתקיף.<br>\n",
    "    אם הפעולה לא קיבלה מופע של שחקן אחר, היא מתקיפה את האויב האחרון שנוסף לרשימת <var>nemeses</var> של השחקן.<br>\n",
    "        אם הפעולה לא קיבלה מופע של שחקן אחר ואין לשחקן אויבים, הפעולה תקפיץ <var>IndexError</var>.\n",
    "    </li>\n",
    "    <li>פעולת \"<var>revive</var>\" – מחזירה לשחקן את החיים לערך המרבי שלהם.</li>\n",
    "</ul>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    אם בעקבות פעולת התקפה שחקן מסוים הגיע ל־0 חיים או פחות מכך, הוא נחשב למת ברובו.<br>\n",
    "    דאגו שהשחקן יעבור החייאה וצרפו את מי שהתקיף אותו לרשימת ה־<var>nemeses</var> של השחקן.\n",
    "</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<p style=\"text-align: right; direction: rtl; float: right; clear: both;\">\n",
    "    תעדו את התוכנית שלכם היטב.\n",
    "</p>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}