راهنمای سبک مستندسازی¶

این راهنما شامل اطلاعاتی در مورد سبک مورد انتظار، نحو خاص MkDocs، ابزارهای مختلف مورد نیاز و ترجمه مستندات است، با توجه به نوشتن محتوای جدید و ترجمه محتوای موجود.

سبک عمومی¶

در سربرگ‌ها و عناوین، تنها کلمهٔ اول باید با حروف بزرگ نوشته شود.
ما املای آمریکایی را ترجیح می‌دهیم، با برخی آزادی‌ها برای اصطلاحات عامیانهٔ خاص برنامه‌نویسی (مثلاً «apps») و فعل‌کردن اسامی (مثلاً «scrollable»).
هجی «artefact» و «artefacts» همان‌گونه است که نشان داده شده است.
ما پس از نقطه از یک فاصلهٔ ساده استفاده می‌کنیم.
ما از یک خط تیرهٔ ساده که با فاصله‌ها احاطه شده است، به‌عنوان خط تیرهٔ ام (یا عبارت صریح HTML — ) استفاده می‌کنیم.
هر ارجاع به نام یک محصول باید از شیوه‌ٔ نگارش بزرگ‌نویسی ترجیحی آن محصول استفاده کند. (مثلاً "macOS"، "GTK"، "pytest"، "Pygame"، "PyScript").
اگر یک واژه به‌عنوان «کد» استفاده می‌شود، باید به‌صورت کد درون‌خطی با قرار دادن آن در میان تک‌تیرهای پشتی نقل شود، نه اینکه به فرهنگ لغت اضافه شود.
ما از به‌کار بردن اصطلاحاتی مانند «به‌سادگی»، «فقط» یا «به‌آسانی» هنگام توصیف اقداماتی که کاربر باید انجام دهد، خودداری می‌کنیم. این اصطلاحات ممکن است تحقیرآمیز تلقی شوند، به‌ویژه زمانی که کاربر با مشکل مواجه است.

اطلاعات ارجاع متقابل¶

شما باید هر زمان که ممکن است محتوای مستندات را به‌طور متقابل بررسی کنید. این بخش روش‌های مختلفی را که می‌توانید این کار را انجام دهید پوشش می‌دهد، که هر یک بر اساس نوع اطلاعاتی است که ارجاع داده می‌شود.

MkDocs پیوندهای قالب‌بندی‌شده با مارک‌داون استاندارد را رندر می‌کند. پیوندهای وب قالب‌بندی‌شده با مارک‌داون استاندارد به شرح زیر هستند:

[Link text](https://example.com/)

شما همچنین می‌توانید از این قالب برای لینک دادن به یک فایل محلی استفاده کنید:

[Link text](path/to/file.md)

ارجاع به بخش‌های مشخصی از فایل‌ها یا مستندات API نیازمند استفاده از قالب لینک مرجع MkDocs است.

لنگرهای مارک‌داون سفارشی و ارجاع متقابل محتوا¶

Markdown برای همه سربرگ‌ها (هر چیزی در یک خط که با یک تا شش نماد # شروع شود) بر اساس محتوای سربرگ، لنگرها تولید می‌کند. برای مثال، لنگر تولیدشده برای این بخش custom-markdown-anchors-and-content-cross---referencing است. با این حال، به دلیل نحوه کار ترجمه‌های ما، هر بار که به سربرگ بخشی ارجاع داده می‌شود، باید یک لنگر سفارشی داشته باشد.

MkDocs از رندر کردن سینتکس لینک مرجع پشتیبانی می‌کند که به شما امکان می‌دهد با استفاده از یک لینک مارک‌داون اصلاح‌شده به عناصر مختلف مستندات لینک دهید. این شامل لینک دادن به، در میان موارد دیگر، سربرگ‌های سفارشی مارک‌داون و لنگرهای متنی می‌شود.

پیوندهای مرجع MkDocs هر پیوندی هستند که به شکل زیر قالب‌بندی شده‌اند:

[Link text][link-target]

سربرگ سفارشی و لنگرهای محتوا الزامی هستند.

هر سربرگ یا بخش محتوایی که از طریق لینک مرجع MkDocs در مستندات BeeWare در متن محتوا به آن ارجاع داده شده است، باید یک لنگر سفارشی به آن متصل شود. در غیر این صورت، هنگام ترجمه محتوای سربرگ احتمال شکسته شدن لینک‌ها وجود دارد.

اگر نیاز دارید به یک لنگر سربرگی لینک دهید، باید یک لنگر سفارشی برای محتوای مورد نظر ایجاد کنید. نحو کلی برای تعیین یک لنگر سفارشی به شرح زیر است:

# Header text { #anchor-name }

برای مثال، سفارشی‌سازی لنگر این بخش به custom-anchors با قالب‌بندی زیر انجام می‌شود:

## Custom Markdown anchors { #custom-anchors }

شما همچنین می‌توانید یک لنگر روی محتوای عمومی، از جمله متن و بلوک‌های کد، ایجاد کنید. قالب‌بندی زیر، با خطوط جدید در بالا و پایین، باید بالای محتوایی که می‌خواهید به آن پیوند دهید قرار گیرد:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

پس از ایجاد لنگرهای سفارشی، می‌توانید از درون همان سند یا در بخش‌های دیگر مستندات به آن‌ها پیوند دهید.

مارک‌داون استاندارد برای لینک‌دادن به یک لنگر در همان فایل استفاده می‌شود که به شکل زیر قالب‌بندی می‌شود:

[Link text](#anchor-name)

لینک‌دادن به یک لنگر در سند جداگانه از سبک لینک مرجع MkDocs استفاده می‌کند که به شکل زیر قالب‌بندی می‌شود:

[Link text][anchor-name]

لینک‌های مرجع API¶

لینک‌گذاری مرجع MkDocs همچنین از ارجاع متقابل مستندات API پشتیبانی می‌کند، از جمله کلاس‌های مستندشده، متدها یا ویژگی‌های کلاس، و ارجاعات مستندات خارجی خاص.

گزینه‌های متعددی برای لینک‌دادن به یک کلاس مستند یا یک متد یا ویژگی کلاس وجود دارد، صرف‌نظر از اینکه لینک را از همان فایل یا فایلی جداگانه انجام می‌دهید. هنگام لینک‌دادن به کلاس‌ها و غیره، باید در اولین جفت کروشه از بک‌تیک استفاده کنید تا نام به صورت کد درون‌خطی نمایش داده شود. بک‌تیک‌ها تنها در صورتی ضروری نیستند که از متن سفارشی استفاده می‌کنید که نباید به صورت کد درون‌خطی نمایش داده شود. تیرک‌های معکوس هرگز نباید در مجموعه دوم کروشه‌ها قرار گیرند.

لینک‌دادن به یک کلاس در حالی که فضای نام نمایش داده می‌شود، به شکل زیر قالب‌بندی می‌شود:

[`module.ClassName`][]

لینک‌دهی به یک کلاس در حالی که تنها نام کلاس نمایش داده می‌شود، به شکل زیر قالب‌بندی می‌شود:

[`ClassName`][module.ClassName]

ویژگی‌ها همانند موارد بالا هستند، با ذکر نام ویژگی. مثال زیر فضای نام را نمایش می‌دهد:

[`module.ClassName.attributename`][]

همانند کلاس‌ها، نمایش تنها نام ویژگی به شکل زیر قالب‌بندی می‌شود:

[`attributename`][module.ClassName.attributename]

متدها باید پس از فضای نام با () نمایش داده شوند و بنابراین باید به‌طور متفاوتی نسبت به ویژگی‌ها مدیریت شوند. روش مناسب برای لینک‌دادن به یک متد به شرح زیر است:

[`module.ClassName.methodname()`][module.ClassName.methodname]

خروجی زیر تنها نام کلاس و متد را نمایش می‌دهد. این همچنین مستلزم درج پرانتزها پس از نام است:

[`Classname.methodname()`][module.Classname.methodname]

می‌توانید هنگام نمایش هر متنی، با استفاده از همان روش در فضای نام مربوطه، به یک کلاس، متد یا ویژگی لینک دهید. این کار برای کلاس به شکل زیر قالب‌بندی می‌شود:

[link text][module.ClassName]

همچنین می‌توان مستقیماً به مستندات اصلی پایتون و همچنین مستندات Pillow لینک داد. برای مثال، برای لینک دادن به مستندات int:

[`int`][]

برای لینک دادن به مستندات Pillow Image:

[`PIL.Image.Image`][]

نکات بلوک کد¶

زبان و برجسته‌سازی کد¶

می‌توانید زبان کد داخل بلوک کد را با درج نام زبان پس از سه بک‌تیل اول، بدون فاصله، مشخص کنید. این کار هنگام رندر شدن کد، هایلایت مناسب را فراهم می‌کند. برای مثال، برای مشخص کردن پایتون، بلوک کد را با ```python آغاز می‌کنید.

دستورات کنسول و دکمهٔ کپی¶

اگر دستورات کنسول یا دستوراتی با خروجی را درج می‌کنید، بسته به اینکه در حال توصیف یک سیستم‌عامل شبیه یونیکس (از جمله macOS) یا ویندوز هستید، می‌توانید آن را با console یا doscon برچسب‌گذاری کنید. می‌توانید پرامپت ارائه‌شده توسط سیستم‌عامل را نیز وارد کنید؛ هنگام کلیک روی دکمهٔ کپی تنها دستور کپی خواهد شد. برای مثال، اگر یک بلوک کد را با ```console آغاز کنید و محتوای زیر را در آن قرار دهید:

$ mkdir test
$ ls
test

سپس با کلیک روی دکمهٔ کپی در بلوک کد، تنها دستورات کپی می‌شوند و ورودی‌ها و خروجی‌ها نادیده گرفته می‌شوند. این امکان را به شما می‌دهد که نشان دهید این‌ها دستورات کنسول هستند، در حالی که همچنان کاربران می‌توانند به‌طور مؤثر از دکمهٔ کپی استفاده کنند.

هایلایت خطوط خاص کد¶

می‌توانید خطوط خاصی از کد را برجسته کنید. برای مثال، برای برجسته‌سازی خط ۲، یک فاصله بعد از زبان اضافه کرده و سپس {hl_lines="2"} را قرار می‌دهید. بنابراین، بلوک کد شما با ```python {hl_lines="2"} شروع می‌شود. نتیجه:

import toga
from toga.style.pack import COLUMN, ROW

می‌توانید چندین خط مختلف را برجسته کنید. برای مثال، python {hl_lines="3 5 9"} خطوط ۳، ۵ و ۹ را برجسته می‌کند. همچنین می‌توانید یک بازه از خطوط را برجسته کنید. برای مثال، python {hl_lines="3-8"} خطوط ۳ تا ۸ را برجسته می‌کند. می‌توانید چندین بازه را با، برای مثال، python {hl_lines="9-18 23-44"} برجسته کنید.

عناصر مارک‌داون که به قالب‌بندی خاص نیاز دارند¶

به‌دلیل نحوه تولید فایل‌های ترجمه، ضروری است خطوط خالی لازم را در سینتکس مارک‌داون برای هشدارها، یادداشت‌ها، تب‌ها، دستورهای جینجا، زیرنویس تصاویر و هم‌ترازی و غیره درج کنید.

تذکرات و یادداشت‌ها¶

هشدارها باید به شکل زیر قالب‌بندی شوند، و اطمینان حاصل شود که قبل و بعد از شروع و پایان هشدار یک خط جدید قرار گیرد:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

این روش برای هر نوع هشدار پشتیبانی‌شده به یک شکل عمل می‌کند. برای مثال، هشدارهای note به همان قالب‌بندی و خطوط جدید نیاز دارند:

Content above.

/// note | Note title

Note text here.

///

Content below.

تمام انواع هشدارهای پشتیبانی‌شده برای استفاده به‌عنوان هشدار در دسترس هستند.

محتوای برگه‌ای¶

محتوای تب‌شده به شکل زیر قالب‌بندی می‌شود، شامل یک خط جدید قبل از شروع و بعد از پایان بلوک محتوا:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

یک تب با هشدار تو در تو به شکل زیر قالب‌بندی می‌شود، شامل یک خط جدید قبل و بعد از بلوک محتوا:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

محتوای جمع‌شده¶

محتوای جمع‌شده به شکل زیر قالب‌بندی می‌شود، شامل خطوط جدید:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

تمام انواع هشدار پشتیبانی‌شده برای استفاده با محتوای جمع‌شده در دسترس هستند، اما باید آن‌ها را به‌عنوان details-admonitiontype اعلام کنید. بنابراین، یک بلوک جمع‌شده از نوع «note» به شکل details-note (همان‌طور که در بالا نشان داده شده) خواهد بود، یک بلوک جمع‌شده از نوع «warning» به شکل details-warning خواهد بود و غیره.

دستورالعمل‌های جینجا¶

چند ویژگی در مستندات وجود دارد که در متن از دستورات Jinja استفاده می‌کنند. هر چیزی که از ویژگی‌های دستور Jinja استفاده می‌کند باید با خطوط جدید احاطه شود. برای مثال، آموزش BeeWare شامل شرط‌های Jinja بر اساس متغیرهاست تا مشخص کند چه هشداری را در صفحهٔ اصلی نمایش دهد. این‌ها به شکل زیر قالب‌بندی شده‌اند:

Content above.



Content below.

همچنین نحوی برای جایگزینی نمادها یا متن وجود دارد. این نحوی متغیری است که در یک جفت براکت دوبل مطابقت‌دار قرار گرفته و اگر در خط جداگانه باشد، باید قبل و بعد از آن یک خط جدید قرار گیرد.

Content above.

{{ variable }}

Content below.

قالب‌بندی تصویر¶

تصاویر می‌توانند عرض‌شان تنظیم شود و می‌توانند در سمت چپ، راست و مرکز تراز شوند (با یک نکته در مورد «مرکز»). تصاویر باید همیشه شامل متن جایگزین معنادار برای اهداف دسترسی‌پذیری باشند.

تنظیم عرض 300px برای یک تصویر به شکل زیر قالب‌بندی می‌شود:

![Image alt text](../path/to/image.png){ width="300px" }

تراز کردن یک تصویر به سمت چپ (یا راست) به شکل زیر قالب‌بندی می‌شود:

![Image alt text](../path/to/image.png){ align=left }

افزودن توضیحات زیر تصویر نیازمند یک خط جدید قبل و بعد از آن است و به شکل زیر قالب‌بندی می‌شود:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

هم‌تراز کردن مرکز تصویر با ویژگی align امکان‌پذیر نیست. راه‌حل این است که پس از تصویر یک عنوان خالی قرار دهید تا تصویر در مرکز قرار گیرد. باید بین هر بخش و قبل و بعد از آن خط‌های جدید قرار دهید. این به شکل زیر قالب‌بندی می‌شود:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

افزونه‌هایی با قالب‌بندی خاص مارک‌داون¶

بخش‌های زیر نحوهٔ استفاده از افزونه‌هایی را که به قالب‌بندی خاص مارک‌داون نیاز دارند، پوشش می‌دهند.

استفاده از اسنیپت‌ها برای درج محتوای خارجی¶

برای جزئیات نحوهٔ درج محتوای خارجی از یک فایل محلی یا یک URL، به مستندات افزونهٔ Snippets مراجعه کنید. تا زمانی که سند حاوی دستورهای Jinja نباشد که نیاز به اجرا داشته باشند، باید از Snippets استفاده شود (اجرای Jinja هم‌زمان با پردازش Snippets انجام می‌شود و بنابراین هیچ Jinja در فایل پردازش نخواهد شد). استفاده از Snippets زمانی ضروری است که بخواهید از جداکننده‌هایی استفاده کنید که به شما امکان می‌دهند بخش‌های خاصی از یک فایل را به صورت جداگانه وارد کنید، مثلاً سند منبع به بخش‌هایی تقسیم شده باشد تا به صورت جداگانه تزریق شوند.

نکات مهم:

ما از -8<- به‌عنوان شناسه‌ی Snippets استفاده می‌کنیم. مستندات چندین گزینه را نشان می‌دهد؛ لطفاً سبک ما را رعایت کنید.
فایل‌های یافت‌شده در محتوای مشترک BeeWare Docs Tools به‌عنوان محتوای «محلی» در نظر گرفته می‌شوند. بنابراین، یا فقط از نام فایل استفاده می‌کنید، مانند -8<- "docs-style-guide.md"، یا اگر محتوا در یک زیرپوشه باشد، فقط از نام پوشه و نام فایل استفاده می‌کنید، مانند -8<- "style/docs-style-guide.md".
اگر در حال درج محتوای خارجی از یک فایل در گیت‌هاب از طریق یک URL هستید، باید حتماً از URL محتوای خام استفاده کنید، وگرنه صفحهٔ وب کامل در هر جایی که آن را درج می‌کنید، نمایش داده خواهد شد.

استفاده از ماکروها برای درج محتوا از محتوای مشترک ابزارهای مستندات BeeWare¶

شما همچنین می‌توانید با استفاده از افزونه Macros MkDocs محتوای موجود در دایرکتوری محتوای مشترک ابزارهای BeeWare Docs را وارد کنید. این روش زمانی ضروری است که سند حاوی دستورهای Jinja باشد که نیاز به اجرا دارند و باید تنها در این شرایط استفاده شود. این روش با محتوای خارجی از طریق URL کار نخواهد کرد. مکانیزم جایگزینی متغیرهای Macros با این روش کار می‌کند.

گزینه‌هایی برای درج محتوا با استفاده از ماکروها وجود دارد:

اگر می‌خواهید سند را بدون هیچ تغییر دستی دیگری درج کنید، از سینتکس Jinja با include استفاده کنید.
اگر سینتکس Jinja extends را در سند گنجانده‌اید، از [سینتکس (https://jinja.palletsprojects.com/en/stable/templates/#child-template) Jinja]block استفاده کنید که به شما امکان می‌دهد بخش‌های مشخصی را بازنویسی یا به آن‌ها افزودنی اضافه کنید.

`pyspelling`¶

ما از SpellChecker pyspelling استفاده می‌کنیم. این SpellChecker در طول بررسی‌های lint اجرا می‌شود.

وقتی pyspelling یک کلمهٔ املایی نادرست را شناسایی می‌کند، در اغلب موارد باید در محتوای مستندات اصلاح شود.

در مورد نادر که یک کلمهٔ معتبر را شناسایی می‌کند که در فرهنگ لغت pyspelling وجود ندارد، دو گزینه دارید:

اگر کلمه‌ای است که احتمال دارد چندین بار دوباره استفاده شود، باید آن را به صورت الفبایی به سند spelling_wordlist در دایرکتوری docs اضافه کنید.
اگر کلمه‌ای باشد که احتمالاً دیگر استفاده نشود، می‌توانید آن را در تگ <nospell> / </nospell> قرار دهید و pyspelling آن را به‌صورت درون‌خطی نادیده می‌گیرد.