RST guidelines and cheat sheet¶

مهم

We strongly recommend reading the راهنمای محتوا and main مستندات pages before contributing.

Follow the RST guidelines below when contributing to the documentation to help maintain consistency with the rest of the documentation and facilitate the review process for the team:

Use formatting.
Be consistent with indentation.
Start a new line before the 100th character.

For hyperlinks:

Use relative links for internal URLs.
Do not break hyperlink targets when refactoring.
Do not use non-descriptive hyperlink labels.

قالب‌بندی¶

Use specific formatting to improve clarity and readability. For example, apply انتخاب منو for menu paths, GUI عنصر for other user interface elements, such as fields, buttons, and options, یادداشت for notes, مثال for examples, etc.

توجه

Add a blank line between different block elements, such as paragraphs, lists, and directives to ensure proper rendering and formatting.

پیوندها¶

Internal URLs: relative links¶

If you need to reference an internal documentation page or a file that is not located in the same directory as the current page, always use relative file paths instead of absolute file paths. This ensures that links remain valid even with version updates, folder name changes, and directory structure reorganizations.

An absolute file path indicates the target's location from the root directory. A relative file path uses smart notations (such as ../ that redirects to the parent folder) to indicate the target's location relative to that of the source document.

مثال

توجه

The purpose of the following example is to illustrate the difference between absolute and relative links. Always use Documentation page hyperlinks when referencing documentation pages.

Given the following source file tree:

documentation
├── content
│   └── applications
│   │   └── sales
│   │   │   └── sales
│   │   │   │   └── products_prices
│   │   │   │   │   └── products
│   │   │   │   │   │   └── import.rst
│   │   │   │   │   │   └── variants.rst
│   │   │   │   │   └── prices.rst

A reference to prices.rst and variants.rst could be made from import.rst as follows:

مطلق:
- documentation/content/applications/sales/sales/products_prices/prices.rst
- documentation/content/applications/sales/sales/products_prices/products/variants.rst
نسبی:
- ../prices.rst
- variants.rst

Refactoring: hyperlink targets¶

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

Hyperlink labels¶

Do not use non-descriptive labels for hyperlinks.

مثال

Good example (descriptive label):

Please refer to the Accounting documentation.

Bad example (non-descriptive label):

Please refer to this page.

Indentation¶

فقط از فاصله استفاده کنید (هرگز از تب‌ها).

Use as many spaces at the beginning of an indented line as needed to align it with the first character of the markup in the line above. This usually implies three spaces, but you only need two for bulleted lists, for example.

مثال

The first : is below the i (three spaces):

.. image:: media/example.png
   :alt: example

The :titlesonly: and page references start below the t (three spaces):

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

Continuation lines resume below the I’s of "Invoice" (two spaces):

- Invoice on ordered quantity: invoice the full order as soon as the sales order is confirmed.
- Invoice on delivered quantity: invoice on what was delivered even if it is a partial
  delivery.

100th-character limit¶

In RST, it is possible to break a line without forcing a line break on the rendered HTML. Make use of this feature to write lines of maximum 100 characters. It is not necessary to leave a trailing whitespace at the end of a line to separate words.

نکته

You can safely break a line on any space, even inside markups such as menuselection and doc.
Some external hyperlinks may exceed 100 characters, but leaving them on a single line is acceptable.

مثال

To register your seller account in Odoo, go to :menuselection:`Sales --> Configuration -->
Settings --> Amazon Connector --> Amazon Accounts` and click :guilabel:`Create`. You can find
the **Seller ID** under the link :guilabel:`Your Merchant Token`.

تیترها¶

For each formatting line (e.g., ===), write as many symbols (=) as there are characters in the header.

نمادهایی که برای قالب‌بندی استفاده می‌شوند، در واقع اهمیت ندارند. تنها ترتیب نوشتن آن‌ها مهم است، زیرا این ترتیب اندازه تیتر تزئین‌شده را تعیین می‌کند. این بدان معناست که ممکن است با قالب‌بندی تیترهای متفاوت و به ترتیبی متفاوت مواجه شوید، در این صورت باید از قالب‌بندی موجود در سند پیروی کنید. در سایر موارد، از قالب‌بندی زیر استفاده کنید.

اندازه تیتر	قالب‌بندی
H1	======= Heading =======
H2	Heading =======
H3	Heading -------
H4	Heading ~~~~~~~
H5	Heading *******
H6	Heading ^^^^^^^

مهم

Each document must have exactly one H1 heading.

مارک‌آپ‌ها¶

تأکید (ایتالیک)¶

برای تأکید بر بخشی از متن. متن به صورت ایتالیک نمایش داده می‌شود.

اطلاعات را قبل از ذخیره فرم پر کنید.

Fill out the information *before* saving the form.

تأکید قوی (بولد)¶

برای تأکید بر بخشی از متن. متن به صورت بولد نمایش داده می‌شود.

یک زیردامنه دامنه‌ای است که بخشی از یک دامنه دیگر است.

A **subdomain** is a domain that is a part of another domain.

اصطلاح فنی (حرفی)¶

برای نوشتن اصطلاح فنی یا مقدار خاصی که باید درج شود. متن به صورت حرفی نمایش داده می‌شود.

آدرس IP چاپگر خود را وارد کنید، مثلاً 192.168.1.25.

Insert the IP address of your printer, for example, `192.168.1.25`.

تعاریف¶

از مارک‌آپ dfn برای تعریف یک اصطلاح استفاده کنید.

مستندات به زبان RST نوشته شده است و باید (به HTML تبدیل شود) تا به‌خوبی نمایش داده شود.

The documentation is written in RST and needs to be built (:dfn:`converted to HTML`) to
display nicely.

مخفف‌ها¶

از مارک‌آپ abbr برای نوشتن یک مخفف خودتعریف استفاده کنید که به عنوان یک راهنمای ابزار نمایش داده می‌شود.

Odoo از OCR و فناوری‌های هوش مصنوعی برای تشخیص محتوای اسناد استفاده می‌کند.

Odoo uses :abbr:`OCR (optical character recognition)` and artificial intelligence
technologies to recognize the content of the documents.

GUI عنصر¶

Use the guilabel markup to identify any text of the interactive user interface (e.g., labels).

اعتبارنامه‌های خود را به‌روزرسانی کنید، سپس روی ذخیره کلیک کنید.

Update your credentials, then click on :guilabel:`Save`.

توجه

Avoid using the guilabel markup when referring to a concept or general term.

مثال

Good example:

To create a credit note, go to Accounting ‣ Customers ‣ Invoices, open the invoice, and click Credit Note.
Bad example:

To create a Credit Note, go to Accounting ‣ Customers ‣ Invoices, open the Invoice, and click Credit Note.

انتخاب منو¶

Use the menuselection markup to guide users through a sequence of menus, starting with the app's name.

To review sales performance, go to Sales ‣ Reporting ‣ Dashboard.

To review sales performance, go to :menuselection:`Sales --> Reporting --> Dashboard`.

توجه

Only include actual menu items in the menuselection markup:

Use the GUI عنصر markup for other user interface elements, such as buttons and section titles:

To configure the bill control policy, navigate to :menuselection:`Purchase --> Configuration
--> Settings`, and scroll down to the :guilabel:`Invoicing` section. Under :guilabel:`Bill
Control`, select either :guilabel:`Ordered quantities` or :guilabel:`Received quantities`.

Do not include menu section names. For example, in the screenshot below, Journals should not be included in the menu path Accounting ‣ Accounting ‣ Journal Entries:

فایل¶

از مارک‌آپ file برای نمایش مسیر یا نام یک فایل استفاده کنید.

Create redirections using the redirects.txt file found at the root of the repository.

Create redirections using the :file:`redirects.txt` file found at the root of the
repository.

دستور¶

برای برجسته‌سازی یک دستور از مارک‌آپ command استفاده کنید.

دستور make clean html را اجرا کنید تا فایل‌های ساخته شده موجود حذف شده و مستندات به HTML ساخته شوند.

Run the command :command:`make clean html` to delete existing built files and build the
documentation to HTML.

Icons¶

Use the icon markup to add the class name of an icon. There are two icon sets used in Odoo: FontAwesome4 and Odoo UI. Follow the icon with its name as a GUI عنصر in brackets as a descriptor.

The graph view is represented by the (area chart) icon. The pivot view is represented by the icon.

The graph view is represented by the :icon:`fa-area-chart` :guilabel:`(area chart)` icon.
The pivot view is represented by the :icon:`oi-view-pivot` icon.

لیست‌ها¶

لیست گلوله‌دار¶

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

- This is a bulleted list.
- It has two items, the second
  item uses two lines.

لیست شماره‌دار¶

این یک لیست شماره‌دار است.
شماره‌گذاری به صورت خودکار انجام می‌شود.

#. This is a numbered list.
#. Numbering is automatic.

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

6. Use this format to start the numbering
   with a number other than one.
#. The numbering is automatic from there.

نکته

Prefer the use of autonumbered lists with #. instead of 1., 2., etc. for better code resilience.

لیست‌های تو در تو¶

نکته

Add a blank line before the nested elements in lists.
Indent nested lists properly, with sub-items aligned under their parent item.

این اولین آیتم از یک لیست گلوله‌دار است.
1. این شامل یک لیست شماره‌دار تو در تو است.
2. با دو آیتم.

- This is the first item of a bulleted list.

  #. It has a nested numbered list
  #. with two items.

پیوندها¶

پیوندهای خارجی¶

External hyperlinks are links to a URL with a custom label. They follow the syntax: `label <URL>`_.

توجه

Use documentation page hyperlinks when targeting another documentation page.
Do not use non-descriptive hyperlink labels.

برای مثال، این یک پیوند خارجی به وب‌سایت اودو است.

For instance, `this is an external hyperlink to Odoo's website <https://www.odoo.com>`_.

مستعارهای پیوندهای خارجی¶

External hyperlink aliases allow creating shortcuts for external hyperlinks. The definition syntax is as follows: .. _target: URL. There are two ways to reference them, depending on the use case:

target_ creates a hyperlink with the target name as label and the URL as reference. Note that the _ moved after the target.
`label <target_>`_ the label replaces the name of the target, and the target is replaced by the URL.

یک اثبات مفهوم نسخه‌ای ساده‌شده و نمونه‌ای از آنچه انتظار می‌رود، برای توافق بر روی خطوط اصلی تغییرات است. PoC یک اختصار رایج است.

.. _proof-of-concept: https://en.wikipedia.org/wiki/Proof_of_concept

   A proof-of-concept_ is a simplified version, a prototype of what is expected to agree on
   the main lines of expected changes. `PoC <proof-of-concept_>`_ is a common abbreviation.

لنگرهای سفارشی¶

Custom anchors follow the same syntax as external hyperlink aliases but without any URL. They allow referencing a specific part of a RST file by using the target as an anchor. When users click the reference, they are taken to the part of the documentation page where the target is defined.

The definition syntax is: .. _target:. There are two ways to reference them, both using the ref markup:

:ref:`target` یک پیوند به لنگر با سرخط تعریف شده در پایین به عنوان برچسب ایجاد می‌کند.
:ref:`label <target>` یک پیوند به لنگر با برچسب داده شده ایجاد می‌کند.

مهم

As targets are visible from the entire documentation when referenced with the ref markup, prefix the target name with the app/section name and the file name, separated by slashes, e.g., accounting/taxes/configuration.

توجه

Add custom anchors for all headings so they can be referenced from any documentation file or within Odoo using documentation links.
Notice that there is no _ at the end, contrary to what is done with external hyperlinks.

Please refer to the پیوندها section to learn more about relative links.

 .. _contributing/rst/hyperlinks-guidelines:

 Hyperlinks
 ==========

.. _contributing/rst/relative-links:

Use relative links for internal URLs
------------------------------------

Please refer to the :ref:`<contributing/rst/hyperlinks-guidelines>` section to learn more
about :ref:`relative links <contributing/rst/relative-links>`.

Documentation page hyperlinks¶

The doc markup allows referencing a documentation page wherever it is in the file tree through a relative file path. There are two ways to use the markup, both using the doc markup:

:doc:`path_to_doc_page` creates a hyperlink to the documentation page with the title of the page as label.
:doc:`label <path_to_doc_page>` creates a hyperlink to the documentation page with the given label.

Please refer to the Accounting documentation to learn more about فاکتورهای مشتری.

Please refer to the :doc:`Accounting documentation <../../../applications/finance/accounting>`
to learn more about :doc:`../../../applications/finance/accounting/customer_invoices`.

مهم

Use relative links for documentation page hyperlinks.

پیوندهای دانلود فایل¶

The download markup allows referencing files (that are not necessarily RST documents) within the source tree to be downloaded.

Download this module structure template to start building your module.

Download this :download:`module structure template <rst_guidelines/my_module.zip>` to start building your module.

توجه

Store the file alongside other media files and reference it using a relative link.

تصاویر¶

The image markup allows inserting images in a document.

.. image:: rst_guidelines/create-invoice.png
   :alt: Create an invoice.

نکته

Images should generally be aligned to the left, which is the default behavior. Use the align parameter to change the alignment, e.g., :align: center.
Use the alt parameter to add تگ‌های ALT, e.g., :alt: Activating the developer mode in the Settings app.
Use the scale parameter to scale the image, e.g., :scale: 75%.

همچنین ملاحظه نمائید

Content guidelines for images

بلوک‌های هشدار (اخطارها)¶

همچنین ببینید¶

همچنین ملاحظه نمائید

.. seealso::
- :doc:`Accounting documentation <../../../applications/finance/accounting>`
- :doc:`../../../applications/sales/sales/invoicing/proforma`
- `Google documentation on setting up Analytics for a website <https://support.google.com/analytics/answer/1008015?hl=en/>`_

یادداشت¶

توجه

Use this alert block to draw the reader's attention and highlight important additional information.

.. note::
   Use this alert block to draw the reader's attention and highlight important additional information.

نکته¶

نکته

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

.. tip::
   Use this alert block to inform the reader about a useful trick that requires an action.

مثال¶

مثال

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

.. example::
   Use this alert block to show an example.

تمرین¶

Exercise

از این بلوک هشدار برای پیشنهاد یک تمرین به خواننده استفاده کنید.

.. exercise::
   Use this alert block to suggest an exercise to the reader.

مهم¶

مهم

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

.. important::
   Use this alert block to notify the reader about important information.

هشدار¶

هشدار

از این بلوک هشدار برای الزام خواننده به پیشرفت با احتیاط با آنچه در هشدار شرح داده شده است استفاده کنید.

.. warning::
   Use this alert block to require the reader to proceed with caution with what is described in the warning.

خطر¶

خطر

از این بلوک هشدار برای جلب توجه خواننده به یک تهدید جدی استفاده کنید.

.. danger::
   Use this alert block to bring the reader's attention to a serious threat.

سفارشی¶

عنوان

این بلوک هشدار را با یک عنوان به انتخاب خود سفارشی کنید.

.. admonition:: Title

   Customize this alert block with a **Title** of your choice.

جدول‌ها¶

جدول‌های لیستی¶

جدول‌های لیستی از لیست‌های شماره‌گذاری شده دو سطحی استفاده می‌کنند تا داده‌ها را به جدول تبدیل کنند. سطح اول نمایانگر ردیف‌ها و سطح دوم نمایانگر ستون‌ها است.

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

.. list-table::
   :header-rows: 1
   :stub-columns: 1

   * - Name
     - Country
     - Favorite colour
   * - Raúl
     - Montenegro
     - Purple
   * - Mélanie
     - France
     - Turquoise

جدول‌های شبکه‌ای¶

جدول‌های شبکه‌ای نمایانگر جدول نهایی هستند و برای کار کردن با آن‌ها بصری‌تر هستند.

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

+-----------------------+--------------+---------------+
|                       | Shirts       | T-shirts      |
+=======================+==============+===============+
| **Available colours** | Purple       | Green         |
|                       +--------------+---------------+
|                       | Turquoise    | Orange        |
+-----------------------+--------------+---------------+
| **Sleeves length**    | Long sleeves | Short sleeves |
+-----------------------+--------------+---------------+

نکته

از = به جای - برای تعریف ردیف‌های سرصفحه استفاده کنید.
جداکننده‌های - و | را برای ادغام سلول‌ها حذف کنید.
Make use of this convenient table generator to build tables. Then, copy-paste the generated formatting into your document.

بلوک‌های کد¶

Use the code-block directive to show example code. Specify the language (e.g., python, xml, etc.) to format the code according to the language's syntax rules.

def main():
    print("Hello world!")

.. code-block:: python

   def main():
       print("Hello world!")

افشاکننده‌ها¶

Answer to the Ultimate Question of Life, the Universe, and Everything

۴۲

.. spoiler:: Answer to the Ultimate Question of Life, the Universe, and Everything

   **42**

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

هشدار

علامت‌گذاری tabs ممکن است در برخی شرایط خوب عمل نکند. به خصوص در موارد زیر:

سرصفحه‌های برگه‌ها قابل ترجمه نیستند.
A tab cannot contain headings.
An alert block cannot contain tabs.
A tab cannot contain custom anchors.

برگه‌های پایه¶

برگه‌های پایه برای تقسیم محتوا به چند گزینه مفید هستند. علامت‌گذاری tabs برای تعریف ترتیب برگه‌ها استفاده می‌شود. هر برگه سپس با علامت‌گذاری tab و به دنبال آن برچسب تعریف می‌شود.

محتوایی اختصاص داده شده به کاربران اودو آنلاین.

.. tabs::

   .. tab:: Odoo Online

      Content dedicated to Odoo Online users.

   .. tab:: Odoo.sh

      Alternative for Odoo.sh users.

   .. tab:: On-premise

      Third version for On-premise users.

برگه‌های تو در تو¶

برگه‌ها می‌توانند داخل یکدیگر تو در تو باشند.

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

.. tabs::

   .. tab:: Stars

      .. tabs::

         .. tab:: The Sun

            The closest star to us.

         .. tab:: Proxima Centauri

            The second closest star to us.

         .. tab:: Polaris

            The North Star.

   .. tab:: Moons

      .. tabs::

         .. tab:: The Moon

            Orbits the Earth.

         .. tab:: Titan

            Orbits Jupiter.

برگه‌های گروهی¶

برگه‌های گروهی برگه‌های ویژه‌ای هستند که بر اساس یک برچسب گروه همگام‌سازی می‌شوند. آخرین گروه انتخاب شده به یاد سپرده می‌شود و به طور خودکار زمانی که کاربر به صفحه بازمی‌گردد یا به صفحه دیگری با گروه برگه‌ها می‌رود انتخاب می‌شود. علامت‌گذاری group-tab برای تعریف برگه‌های گروهی استفاده می‌شود.

C++

int main(const int argc, const char **argv) {
    return 0;
}

def main():
    return

class Main {
    public static void main(String[] args) {}
}

.. tabs::

   .. group-tab:: C++

      C++

   .. group-tab:: Python

      Python

   .. group-tab:: Java

      Java

.. tabs::

   .. group-tab:: C++

      .. code-block:: c++

         int main(const int argc, const char **argv) {
             return 0;
         }

   .. group-tab:: Python

      .. code-block:: python

         def main():
             return

   .. group-tab:: Java

      .. code-block:: java

         class Main {
             public static void main(String[] args) {}
         }

برگه های کد¶

Use the code-tab markup to create code tabs, which are essentially group tabs that treat the tabs' content as a code block. Specify the language to format the code according to the language's syntax rules. If a label is set, it is used for grouping tabs instead of the language name.

#include <iostream>

int main() {
    std::cout << "Hello World";
    return 0;
}

print("Hello World")

console.log("Hello World");

.. tabs::

   .. code-tab:: c++ Hello C++

      #include <iostream>

      int main() {
          std::cout << "Hello World";
          return 0;
      }

   .. code-tab:: python Hello Python

      print("Hello World")

   .. code-tab:: javascript Hello JavaScript

      console.log("Hello World");

کارت‌ها¶

Documentation

Use this guide to acquire the tools and knowledge you need to write documentation.

Step-by-step guide

Content guidelines

List of guidelines, tips, and tricks to help you create clear and effective content.

RST guidelines

List of technical guidelines to observe when writing with reStructuredText.

.. cards::

   .. card:: Documentation
      :target: ../documentation
      :tag: Step-by-step guide
      :large:

      Use this guide to acquire the tools and knowledge you need to write documentation.

   .. card:: Content guidelines
      :target: content_guidelines

      List of guidelines, tips, and tricks to help you create clear and effective content.

   .. card:: RST guidelines
      :target: rst_guidelines

      List of technical guidelines to observe when writing with reStructuredText.

فراداده‌های سند¶

Sphinx supports document-wide metadata markups that specify a behavior for the entire page. They must be placed between colons (:) at the top of the source file.

فراداده	هدف
`نمایش محتوا`	صفحه toctree را از منوی ناوبری در دسترس قرار دهید.
`نمایش فهرست مطالب`	فهرست مطالب را در صفحه‌ای که دارای علامت‌گذاری فراداده `show-content` است، نمایش دهید.
`مخفی‌کردن فهرست مطالب صفحه`	نوار کناری "در این صفحه" را مخفی کنید و از عرض کامل صفحه برای محتوا استفاده کنید.
`بدون جستجو`	سند را از نتایج جستجو مستثنی کنید.
`یتیم`	نیاز به درج سند در toctree را حذف کنید.
`ستون کد`	یک ستون جانبی پویا نمایش دهید که می‌تواند برای نمایش آموزش‌های تعاملی یا گزیده‌های کد استفاده شود. برای مثال، به راهنمای سریع حسابداری مراجعه کنید.
`css سفارشی`	Link CSS files (comma-separated) to the file.
`js سفارشی`	فایل‌های JS (با جداکننده کاما) را به سند لینک کنید.
`کلاس‌ها`	Assign the specified classes to the `<main/>` element of the file.

نکات قالب‌بندی¶

شکستن خط بدون قطع پاراگراف¶

یک خط بلند که آن را به دو قسمت تقسیم می‌کنید -> اینجا <- به‌عنوان یک خط واحد ارائه می‌شود.

یک خط دوم که به دنبال یک شکست خط می‌آید.

| A first long line that you break in two
  -> here <- is rendered as a single line.
| A second line that follows a line break.

Escape markup symbols¶

نمادهای علامت‌گذاری که با بک‌اسلش (\) فرار کرده‌اند به‌طور معمول نمایش داده می‌شوند. برای مثال، this \*\*line of text\*\* with \*markup\* symbols به صورت “this **line of text** with *markup* symbols” نمایش داده می‌شود.

When it comes to backticks (`), which are used in many cases such as external hyperlinks, using backslashes for escaping is no longer an option because the outer backticks interpret enclosed backslashes and thus prevent them from escaping inner backticks. For instance, `\`this formatting\`` produces an [UNKNOWN NODE title_reference] error. Instead, ```this formatting``` should be used to produce the following result: `this formatting`.

همچنین ملاحظه نمائید

Docutils documentation on reStructuredText directives and roles