Doc Authoring Guide (Sphinx/RTD)

מטרות

  • בנייה ללא אזהרות (-W --keep-going / fail_on_warning: true).

  • עקביות בכותרות, קישורים ועוגנים.

מדיניות

  • עמודי סקירה חופפים: הוסיפו :noindex: (api, database, handlers, services, configuration).

  • autodoc_mock_imports: רשימת מודולים כבדים/לא זמינים בזמן build.

  • אין להריץ קוד בזמן import ברמת מודול.

  • עמוד שאינו אמור להתפרסם — ל-**``exclude_patterns``**, לא ליתום. עמוד שאינו רשום באף toctree מייצר document isn't included in any toctree, ומכיוון ש-RTD נכשל על אזהרות זה מפיל את הבילד. exclude_patterns ב-docs/conf.py מרכז את העמודים שהוחרגו בכוונה — למשל כפילויות .md/.rst כשה-MyST פעיל. לפני שמוסיפים החרגה, ודאו שהעמוד באמת לא אמור להיות בתוכן העניינים.

הצהרת תקציר בראש העמוד

  • כל עמוד ידני מצהיר על תקציר בראשו. AI-MAP.md — מפת הניווט לסוכני AI — קורא את ההצהרה הזו ולא מנסה לנחש אותה מהגוף. ההצהרה היא מידע על העמוד ולא חלק ממנו: היא לא מוצגת באתר, ונועדה רק למפה.

  • ב-.rst: שדה :summary: בשורה הראשונה של הקובץ, לפני הכותרת ולפני תוויות והערות, ואחריו שורה ריקה. רשימת שדות שקודמת לכל markup אחר היא מה ש-Sphinx מכנה ”File-wide metadata“: הוא שומר אותה כמידע על העמוד ואינו מציג אותה, בדיוק כמו ה-front matter של עמודי .md. עד אוקטובר 2026 השדה ישב מתחת לכותרת, ושם Sphinx הציג אותו בעמוד — ומשם הוא הגיע לכפתור ”העתק“, לקובץ הייצוא ולכרטיסי החיפוש בתיעוד.

  • תווית אחרי ההצהרה, לא לפניה. תווית (.. _x:) שקודמת לשדה נצמדת אליו ולא לכותרת, וכש-Sphinx מוציא את השדה מהעמוד התווית נשברת בשקט: קישור אליה מקבל את הטקסט ”summary“, העוגן לא קיים בעמוד, ואין שום אזהרה. Sphinx לא מתריע גם על שדה שנשאר מתחת לכותרת, ולכן test_no_rst_page_has_a_summary_away_from_the_top_of_the_file (ב-tests/test_ai_map_generator.py) נכשל על כל :summary: בעמודה 0 שאינו ההצהרה שבראש הקובץ.

  • ב-.md: מפתח summary ב-front matter, שנקרא ב-yaml.safe_load בדיוק כמו ש-MyST קורא אותו.

  • אין הצהרה ← המפה מציגה את הכותרת בלבד. python3 scripts/generate_ai_map.py --check מתריע על עמודים כאלה ואינו מפיל את הבנייה.

  • משפט אחד או שניים, בגוף ההווה, שעונים על ”מה יש בעמוד הזה“. שורת המפה נחתכת ב-220 תווים (SUMMARY_CAP ב-scripts/generate_ai_map.py); ההצהרה בקובץ נשארת מלאה.

  • אל תתחילו בשם העמוד. שורת המפה היא נתיב — **כותרת**: תקציר, כך שהכותרת כבר שם; תקציר שפותח בה מייצר כפילות מיידית (Playbook קצר להתראות: פלייבוק קצר להתראות: ...). התחילו בתוכן.

  • אל תכתבו בתקציר ספירה או הבטחת יכולת. ”שבעה מסלולי API“, ”28 אייקונים“, ”דוגמאות מוכנות להרצה“, ”תומך בחיפוש סמנטי“ — כל אלה טענות שדורשות אימות מול הקוד, והן מתיישנות בלי שאיש ישים לב. שלושה סבבי ריוויו רצופים בפרויקט הזה נפלו בדיוק על זה: ספירה שהשתנתה, קוד עם ... שהוצג כרץ, ו-SearchType שקיים ב-enum ואינו ממומש. תארו מה יש בעמוד, לא כמה ולא מה עובד. tests/test_doc_summary_style.py אוכף את זה על ספירה במילים ועל ספירה בספרות שאחריה מילה עברית — והוא רשת לצורות הנפוצות, לא אישור שהתקציר נכון; מה שהוא במפורש אינו תופס מתועד ב-docstring שלו.

  • אל תשאירו כותרת יתומה. אם ההצהרה מחליפה פסקת פתיחה והסעיף שהכיל אותה נשאר ריק — מחקו גם את הכותרת. סעיף ריק מרונדר בעמוד כשורה ללא גוף.

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

הצורה בראש עמוד .rst שיש לו גם תווית:

:summary: מה יש בעמוד, במשפט אחד או שניים.

.. _my-page:

כותרת העמוד
===========

ספירות בפרוזה: ספירת מופעים לעומת ערך שנאכף

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

  • ספירת מופעים — אל תכתבו. ”בשתי ההפניות לעמוד הזה“, ”28 אייקונים“, ”שבעה מסלולי API“. אף אחד לא שומר על המספר הזה: כל הוספה שוברת אותו, ושום בדיקה לא מתריעה. נסחו בלי כמות — ”בכל מקום שבו העמוד נוגע בנימוק הנדסי“ נכון גם אחרי התוספת הבאה.

  • ערך שנאכף — כן תעדו. ”20 פתקים לקובץ“, ”תקרה של 1000 פתקים למשתמש“, ”עד 500KB לקובץ“. המספר הזה חי בקוד ונאכף בו, ולכן הוא אינו נסחף מעצמו — ומי שקורא את התיעוד חייב אותו. שינוי שלו הוא שינוי מוצר שממילא מחייב עדכון תיעוד.

המבחן: אם המספר יכול להשתנות בלי שאף שורת קוד תשתנה — הוא ספירת מופעים, ואין לכתוב אותו.

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

הטמעת קוד מהמקור (literalinclude)

  • אסור למען לפי מספרי שורות (:lines:) — הקוד זז והתיעוד ממשיך להציג את הטווח הישן בלי שום אזהרה. זה דפוס line-number-coupling (ראו amir-bug-patterns), והוא כבר קרה כאן: בלוק שהצביע על main.py:739 הציג פנימיות של פונקציה אחרת, במרחק 2,900 שורות מהיעד.

  • פונקציה או מחלקה שלמה ← :pyobject:. הקוד נמשך לפי שם בכל בנייה, ושינוי שם מפיל את הבנייה ברעש.

  • קטע בתוך פונקציה ← הערות סימון בקוד בפורמט # docs:<שם>:start / # docs:<שם>:end, ומיעון ב-:start-after: / :end-before:. הערת ה-start חייבת לומר שהתיעוד תלוי בה ולאיזה דף — אחרת הריפקטור הבא ימחק אותה כהערה סתומה.

  • marker חסר מפיל את הבנייה תחת -W (אזהרת docutils, שאינה מושתקת בקונפיגורציה) — נבדק. marker כפול מסוכן יותר: הבלוק ירונדר מהמופע הראשון בלי אזהרה, ולכן כל שם מופיע פעם אחת בדיוק. tests/test_docs_literalinclude_anchors.py אוכף את שני הכללים.

ייצוא הסעיפים בבניית האתר

אחרי שהאתר נבנה ב-documentation.yml, הצעד ”Export doc sections“ מריץ את scripts/docs_export_sections.py, שכותב בתוך האתר את _export/sections.json: כל סעיף בכל עמוד תוכן, כמארקדאון, עם המזהה שלו (העוגן בכתובת), הכותרת כטקסט וכמארקדאון (title_markdown), שביל הכותרות וקובץ המקור, בסדר שבו הסעיפים מופיעים בעמוד; ולכל עמוד, הקבצים האחרים בריפו שהוא נבנה מהם (dependencies: קוד ש-literalinclude מציג, קובץ ש-include משלב, תמונה, מודול ש-autodoc מתעד). את הרשימה הזו Sphinx רושם בעצמו בכל בנייה, והסקריפט הוא גם הרחבה של Sphinx (extensions ב-docs/conf.py) שכותבת אותה ל-_export/dependencies.json בסוף הבנייה; קובץ מחוץ לריפו (מודול של פייתון או של חבילה מותקנת) לא נכנס. הקובץ נפרס יחד עם האתר, והוא הבסיס לחיפוש בתיעוד מתוך הוובאפ ולתצוגה המרונדרת של עמודי rst בדפדפן הקוד: ממנו נבנה האינדקס, ראו אינדקס התיעוד ו-עמודי התיעוד (rst).

  • ההמרה היא זו של כפתור ”העתק תוכן הדף“. הסקריפט פותח כל עמוד בדפדפן (Playwright) ומריץ עליו את window.DocCopyPage.toMarkdown מ-docs/_static/copy-page.js. שינוי בכללי ההמרה שם משנה את הכפתור ואת הייצוא יחד, ואין עותק שני שצריך לעדכן.

  • כותרת בעמוד עם תוכן עניינים. .. contents:: גורם ל-docutils לעטוף את הטקסט של כל כותרת בקישור חזרה לתוכן העניינים (<a class="toc-backref">): זו ברירת המחדל של :backlinks: (toc_backlinks ב-docutils/frontend.py, ו-section_title_tags ב-docutils/writers/_html_base.py, docutils 0.21.2). ההמרה מוציאה את הקישור ומשאירה את הטקסט (UNWRAP_SELECTORS ב-copy-page.js). עד 19.10.2026 היא מחקה את הקישור יחד עם הטקסט, והעתקה של עמוד כזה יצאה בלי הכותרות שלו.

  • המזהה של סעיף. כותרת בעברית שאין מעליה תווית מקבלת מ-Sphinx מספר רץ (id1, id2…), והוא זז כשמוסיפים סעיף לפניה. לכן הקובץ נכתב מאותה בנייה שנפרסת, וקישור שנבנה ממנו מגיע לסעיף הנכון באתר. סעיף שקישורים אליו צריכים להחזיק לאורך זמן מקבל תווית (.. _שם-באנגלית:) מעל הכותרת, ואז התווית היא המזהה שלו. שתי ההתנהגויות נבדקו על הייצוא של האתר כולו, בבנייה עם Sphinx 8.2.3 (7.10.2026). ראו גם Versioning & Stable Anchors.

  • מה לא נכנס: עמודי api/ והעמודים ש-Sphinx מייצר בעצמו (EXCLUDED_TOP_DIRS ו-EXCLUDED_PAGES בסקריפט), ובתוך העמודים בלוקים שנוצרו מהקוד (dl.py). כל קישור הופך לכתובת מלאה באתר, וגם הכתובת של כל תמונה. התמונה נשארת תמונה (![alt](כתובת)), כדי שתוצג בוובאפ.

  • עותק בשם של הקומיט. לצד sections.json נכתב עותק זהה לו בית-בבית, _export/sections-<sha>.json (export_path_for_commit בסקריפט). האתר מוגש מאחורי מטמון (CDN) ששומר כל קובץ עד עשר דקות ומתעלם מה-query: ב-7.10.2026 נמדד מול הקובץ החי ש-?v= אקראי חדש חוזר x-cache: HIT. לכן מי שמבקש את sections.json מיד אחרי פריסה עלול לקבל את הקובץ של הפריסה הקודמת, ואילו לשם שתלוי בקומיט אין עותק במטמון. הוובאפ מבקש את העותק לפי הקומיט שמגיע אליו ב-webhook של הפריסה.

  • כשל בייצוא לא מפיל את בניית האתר. צעדי הייצוא רצים עם continue-on-error: האתר נפרס בלי הקובץ, נכתבת אזהרה בסיכום הריצה, ובבנייה של main נשלחת גם התראה לטלגרם (.github/actions/telegram-message). עמוד אחד שנכשל מכשיל את כל הייצוא, כך שאין קובץ חלקי.

  • הרצה מקומית, על אתר שכבר נבנה: python scripts/docs_export_sections.py docs/_build/html --site-url <כתובת האתר> --source-commit <sha> --source-root docs. צריך Playwright ודפדפן שהוא התקין (python -m playwright install chromium), או --chromium-executable עם נתיב ל-Chromium קיים.

כיוון האתר (מימין לשמאל)

האתר כולו בנוי מימין לשמאל: התפריט בצד ימין, ושורת המיקום, כפתורי ”הקודם“ ו-”הבא“ והתוכן מתהפכים יחד איתו. הכיוון נקבע במקום אחד, ברמת העמוד, ולא בכללים נפרדים לכל אלמנט.

  • מאיפה מגיע dir. _set_text_direction ב-docs/conf.py שואלת את Babel מה הכיוון של השפה שהבנייה רצה בה, ו-docs/_templates/layout.html שם את התשובה על התגית html. הפונקציה רצה ב-config-inited, אחרי ש-Sphinx החיל -D language=, וזו הדרך שבה Read the Docs מעביר את השפה מהדשבורד שלו. לכן הכיוון תמיד תואם לשפה שהאתר נבנה בה בפועל, וגם בנייה באנגלית יוצאת משמאל לימין בלי לגעת בשום דבר. layout.html הוא עותק מלא של התבנית של sphinx_rtd_theme עם שינוי אחד: אצל הערכה התגית html יושבת מחוץ לכל בלוק, ודריסה של בלוק דרך {% extends %} לא מגיעה אליה.

  • ב-custom.css כותבים מאפיינים לוגיים: margin-inline-start, border-inline-start, inset-inline-start, float: inline-start, text-align: start. הם נמדדים מתחילת השורה, ולכן מתהפכים לבד עם העמוד, ואותו CSS נכון בשני הכיוונים. margin-left או direction: rtl על אלמנט בודד נשארים בצד אחד, וזה בדיוק המצב שהיה כאן קודם: רק אזור התוכן התהפך, והתפריט נשאר בשמאל. בשכבת הכיוון שבראש הקובץ מופיע גם מאפיין פיזי, אבל רק כדי לבטל כלל של הערכה (left: auto, margin-left: 0), ותמיד לפני המאפיין הלוגי: כששניהם ממופים לאותו צד, האחרון מנצח.

  • צד קבוע נשאר רק במקומות האלה, וכולם בכוונה: direction: ltr בבלוקי הקוד (.highlight, .literal-block), כדי שקוד יוצג משמאל לימין. border-left בבלוקים של autodoc, שהפס שלהם נשאר בשמאל כי החתימה בימין. והחצים בכפתורי ”הקודם“ ו-”הבא“, שאין להם גרסה לוגית, ולכן הם מתהפכים בכלל עם [dir="rtl"]. הכלל הזה צריך גם display: inline-block, כי transform לא חל על אלמנט inline, והאייקון של הערכה הוא inline.

  • הערכים של הערכה. שכבת הכיוון כותבת שוב ערכים מ-theme.css של הערכה: רוחב התפריט, נקודת השבירה של המובייל וההזחות בתפריט. layout.html הוא עותק של התבנית שלה. שניהם נכונים לגרסה הנעולה ב-docs/requirements.txt, והגרסה כתובה גם בראש layout.html וגם בראש שכבת הכיוון. tests/test_docs_rtl_layer.py נכשל כשאחת משלוש הגרסאות שונה מהאחרות, כש-dir בתבנית לא מקבל את הערך מ-conf.py, וכשמופיעים direction או border-left מחוץ למקומות שלמעלה. בשדרוג של הערכה מעתיקים מחדש את layout.html ומחזירים את dir, מודדים מחדש בדפדפן את הערכים בשכבת הכיוון, ורק אז מעדכנים את הגרסה בשלושת המקומות.

  • תרגום הממשק. המחרוזות של הערכה, כמו ”Previous“, ”Next“ ו-”View page source“, מתורגמות ב-docs/locales/he/LC_MESSAGES/sphinx.po: לערכה אין קטלוג עברי, והקטלוג העברי של Sphinx לא מכיל אותן. Sphinx טוען את הקטלוגים של הפרויקט (locale_dirs, ברירת המחדל locales) לפני הקטלוג שלו, ומקמפל את הקובץ ל-sphinx.mo לידו בכל בנייה. ה-.mo ב-.gitignore. מחרוזת של הערכה שמופיעה באתר באנגלית מתרגמים שם.

  • תיבת הגרסאות של Read the Docs לא שייכת לערכה. היא נטענת מהתוספות של RTD, והמיקום שלה נקבע בדשבורד שלהם (Addons ← Flyout ← Position), לא בקוד. בלי הגדרה היא בפינה הימנית התחתונה (src/flyout.js בריפו readthedocs/addons, קומיט 29ebc618), כלומר מעל התפריט.

התפריט עוקב אחרי הסעיף שקוראים בו

בעמוד שהסעיפים שלו מופיעים בתפריט הצד, הפריט של הסעיף שקוראים בו מסומן בפס דק בצד שבו הטקסט מתחיל, והתפריט נגלל אליו רק כשהוא יוצא מהתצוגה. את זה עושה docs/_static/nav-follow.js, וזו ההתנהגות של תוכן העניינים הצף בתצוגת Markdown בוובאפ (updateActiveItem ב-webapp/templates/md_preview.html). ההערה בראש הסקריפט מפרטת במה הוא שונה ממנו.

  • איזה סעיף מסומן: האחרון שהכותרת שלו עברה את קו הקריאה. ברוב העמוד הקו קבוע ליד ראש המסך (READ_LINE_RATIO), באותו גובה שבו תוכן העניינים בוובאפ מזהה כותרת (CONFIG.INTERSECTION_MARGIN). בקטע האחרון של הגלילה הקו יורד בהדרגה עד תחתית המסך (readLine). בלי זה, הסעיפים האחרונים בעמוד לא היו מסומנים אף פעם, כי העמוד נגמר לפני שהכותרת שלהם מגיעה לקו. כשהפריט של הסעיף מקופל בתפריט, מסומן הפריט המוצג הקרוב שמעליו: הערכה מציגה את תתי-הסעיפים רק של הפריט שנבחר.

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

  • sticky_navigation של הערכה כבוי ב-docs/conf.py. כשהוא דלוק, הערכה גוללת את התפריט באותו מרחק שהעמוד זז, בלי קשר לסעיפים, ובעמוד ארוך התפריט מגיע לפריטים של עמודים אחרים לגמרי. אם מדליקים אותו שוב, שני המנגנונים מזיזים את אותו תפריט.

  • הסימון הוא פס ולא רקע (.doc-nav-active ב-custom.css, וההסבר שם). הסימון של הערכה לפריט שנלחץ, רקע כהה וטקסט מודגש, נשאר כמו שהוא, ויכול להופיע יחד עם הפס על פריט אחר.

  • הבדיקות. tests/docs-nav-follow.test.js בודק את ההחלטות עצמן: איזה סעיף נבחר, איפה הקו ובכמה לגלול. הוא רץ ב-CI, והוא נכשל גם כשקו הקריאה כבר לא זהה לזה של הוובאפ. tests/test_docs_nav_follow_browser.py בונה אתר קטן עם docs/conf.py עצמו ובודק בדפדפן את ההתנהגות כולה, כולל גלילה במגע של טאבלט ו-sticky_navigation. הוא רץ רק כשיש Chromium והתלויות של docs/requirements.txt, כלומר לא ב-CI. הסקריפט נשען על המבנה של התפריט של הערכה, ולכן בשדרוג הערכה מריצים את הבדיקה הזו.

רשומה ב-What’s New

החיפוש בתיעוד מתוך הוובאפ מפרק את What’s New לעדכונים: כל בולט ברשימה של יום הוא תוצאה משלו, עם כותרת משלו וקישור שקופץ אליו בתוך היום, בדפדפן שתומך בקפיצה לטקסט (אינדקס התיעוד, תיעוד). כדי שזה יעבוד:

  • עדכון אחד — בולט אחד. שני שינויים בבולט אחד יחזרו בחיפוש כתוצאה אחת. שורות המשך ורשימה פנימית שייכות לבולט שהן בתוכו.

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

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

  • פתיח קצר. עד MAX_TITLE_BYTES בתים (UTF-8), התקרה של כותרת בקובץ הייצוא (services/docs_export_client.py). פתיח ארוך יותר לא נחתך: העדכון נכנס בשם של היום, ונרשמת אזהרה בלוג של הוובאפ.

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

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

בשורה הראשונה הקוד מוצג באתר עם הגרשיים. בשנייה הפתיח, באתר ובכרטיס של החיפוש, הוא fix (WebApp): השמירה ב-/upload/from-repo עובדת. (נבדק ב-docutils 0.21.2 ובכלל הפתיח של האינדקס):

- **fix (WebApp): השמירה ב-``/upload/from-repo`` עובדת.** הסיבה: …
- **fix (WebApp): השמירה ב-**\ ``/upload/from-repo`` **עובדת.** הסיבה: …

טיפים מהירים

  • אל תריצו את הבנייה המלאה לוקאלית כדבר שבשגרה — שתי בדיקות על ה-PR תופסות אזהרות. הראשונה היא הבנייה של ה-PR ב-documentation.yml (הצעד sphinx_pr), שרצה עם -W ו--E. -W מכשיל אותה על כל אזהרה, ו--E קורא מחדש את כל העמודים: בנייה מצטברת קוראת רק עמודים שהשתנו, ולכן לא מדווחת על קישור שנשבר בעמוד שלא השתנה (נבדק על Sphinx 8.2.3). כדי ש--W יראה את מה שבתיעוד, suppress_warnings ב-conf.py משתיק רק את הרעש של מודולים מדומים (autodoc.import_object ו-autodoc.mocked_object) ולא כל אזהרה של autodoc. וכדי שאתר תיעוד חיצוני שלא זמין לרגע לא יכשיל PR, לכל מלאי ב-intersphinx_mapping יש עותק שמור ב-docs/_intersphinx/, שנטען רק כשהרשת נכשלת. השנייה היא Read the Docs: .readthedocs.yml מגדיר fail_on_warning: true, וה-check שלו יורד לאדום. עד 12.11.2026 רק הוא תפס אזהרות, וכשהבנייות שלו נקטעו ב-”Build terminated due to inactivity“ לא היה מי שיתפוס. הבנייה של main, שמפרסמת את האתר, נשארת בלי -W בכוונה: אזהרה שנכנסה לא עוצרת את הפרסום. docs.yml מריץ בנייה עם -W ידנית (workflow_dispatch), לענף שאין לו PR. tests/test_docs_pr_build_fails_on_warnings.py נועל את הדגלים של שתי הבנייות. לכן בנייה מקומית של פרוזה בעמוד קיים היא בזבוז.

  • אל תסיקו מזה ש-RTD שקול לבנייה המקומית. הוא מתקין docs/requirements.txt משלו ורץ בסביבה אחרת, כך שגרסת Sphinx או תוסף יכולים להתנהג שם אחרת. אם RTD אדום ולוקאלית ירוק — RTD צודק, כי הוא הסביבה שמפרסמת.

  • החריג: עמוד חדש, או נגיעה ב-``toctree``/``conf.py``. שם טעות מפילה את הבילד כמעט בוודאות (document isn't included in any toctree), והבדיקה זולה כי אפשר לבנות עמוד בודד: python -m sphinx -b html -W . _build/html <עמוד>.rst.

  • השתמשו ב‑copybutton לקוד שמיועד ל‑Copy‑Paste.

  • שמרו עוגנים יציבים לכותרות עיקריות.

קישורים