Hướng dẫn RST

Ví dụ

Với cây tệp nguồn sau:

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

Một tham chiếu đến prices.html và variants.html đã được hiển thị từ import.rst có thể được thực hiện như sau:

  1. Tuyệt đối:

    • https://odoo.com/documentation/17.0/applications/sales/sales/products_prices/prices.html

    • https://odoo.com/documentation/17.0/applications/sales/sales/products_prices/products/variants.html

  2. Tương đối:

    • ../prices.html

    • variants.html

Các liên kết tương đối rõ ràng vượt trội về tính đọc dễ và ổn định: các tham chiếu vẫn tồn tại qua các bản cập nhật phiên bản, thay đổi tên thư mục và cấu trúc lại cây tệp.

Bắt đầu một dòng mới trước ký tự thứ 100

Trong RST, có thể ngắt dòng mà không buộc ngắt dòng trong HTML đã được hiển thị. Hãy sử dụng tính năng này để viết các dòng tối đa 100 ký tự. Một ngắt dòng trong một câu sẽ dẫn đến một khoảng trắng thêm trong HTML. Điều đó có nghĩa là bạn không cần phải để lại khoảng trắng dư thừa ở cuối một dòng để phân tách các từ.

Mẹo

Bạn có thể an toàn ngắt một dòng xung quanh các dấu phân cách (-->) của các đánh dấu menuselection và ở bất kỳ đâu trong một tham chiếu liên kết. Đối với các đánh dấu doc, ref và download, điều này chỉ đúng với phần nhãn của tham chiếu.

Ví dụ: Ngắt dòng trong các đánh dấu

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

Đảm bảo nhất quán với việc thụt lề

Chỉ sử dụng khoảng trắng (không bao giờ sử dụng tab).

Sử dụng số lượng khoảng trắng cần thiết ở đầu dòng thụt lề để căn chỉnh với ký tự đầu tiên của đánh dấu trong dòng trên. Điều này thường đòi hỏi 3 khoảng trắng nhưng bạn chỉ cần 2 khoảng trắng cho các danh sách đánh dấu.

Ví dụ: Dấu : đầu tiên nằm dưới chữ i (3 khoảng trắng)

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

Ví dụ: Các đánh dấu :titlesonly: và tham chiếu trang bắt đầu dưới chữ t (3 khoảng trắng)

.. toctree::
   :titlesonly:

   payables/supplier_bills
   payables/pay

Ví dụ: Các dòng tiếp tục tiếp tục dưới các chữ I của “Invoice” (2 khoảng trắng)

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

Sử dụng đánh dấu menuselection

Mặc dù các ký tự nối chuỗi ‣ và tên menu hoạt động tốt để chỉ cho người dùng các menu cần nhấp, nhưng tốt nhất là sử dụng đánh dấu menuselection (xem Sử dụng đánh dấu menuselection) để đạt được kết quả tương tự. Thực tế, nó hiển thị chuỗi menu đồng nhất với phần còn lại của tài liệu và sẽ tự động thích ứng với bảng đồ họa mới nếu chúng tôi chuyển sang một cái mới. Đánh dấu này được sử dụng trong văn bản như sau: :menuselection:`Sales --> Settings --> Products --> Variants`.

Viết mã linh hoạt

  • Ưu tiên sử dụng #. trong danh sách đánh số thay vì 1., 2., v.v. Điều này loại bỏ rủi ro phá vỡ việc đánh số khi thêm các phần tử mới vào danh sách và dễ duy trì hơn.

  • Tránh sử dụng các mục tiêu liên kết ngầm và ưu tiên các mục tiêu liên kết nội bộ thay thế. Tham chiếu đến mục tiêu ngầm How to print quotations? có khả năng bị hỏng hơn so với tham chiếu đến mục tiêu rõ ràng _print_quotation mà không bao giờ xuất hiện trong HTML đã được hiển thị và do đó ít có khả năng bị sửa đổi hơn.