Hướng Dẫn về Kiểu Cách của Dấu Đánh -- Markup Style Guide¶

Trang này bao gồm các quy ước để viết và sử dụng cú pháp dấu đánh Tái Cấu Trúc Văn Bản (RST).

Quy Ước -- Conventions¶

Thụt dòng ba khoảng cách trống.
Số chữ trong các dòng phải ít hơn 120 ký tự.
Dùng chữ nghiêng cho các tên của nút bấm/trình đơn.

Những quy tắc ước lệ khác:

Tránh không dùng các ký tự trong bộ phông Unicode.
Tránh xuống dòng quá nhiều (chẳng hạn, mỗi câu một dòng).

Tiêu Đề -- Headings¶

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Ghi chú

Phần -- Parts chỉ nên được sử dụng cho nội dung, hoặc ở các trang mục lục mà thôi.

Ghi chú

Mỗi tập tin .rst chỉ nên có một tiêu đề cho chương (*) mà thôi.

Kiểu Chữ -- Text Styling¶

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

Sau đây là các dấu đánh hữu ích để tạo kiểu cách cho văn bản:

*italic*
**bold**
``literal``

Phần Tử Giao Diện -- Interface Elements¶

:kbd:`NCT (LMB)` -- tổ hợp phím bấm nhanh và bố trí chuột.
*Đối Xứng Hóa/Phản Quang -- Mirror* -- nhãn giao diện.
:menuselection:`3D Viewport --> Add --> Mesh --> Monkey` -- menus.

Operator Menus¶

Each operator should receive its own heading or page based on the length of the content. Each operator should have a reference admonition documenting the context of the operator:

.. admonition:: Reference
   :class: refbox

   :Mode:      Edit Mode
   :Menu:      :menuselection:`Curve --> Snap`
   :Hotkey:    :kbd:`Shift-S`

Panels¶

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

Panel Title
===========

Nested Panel Title
------------------

Properties¶

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

Property
   Property description.

   Hidden Property
      Hidden property description.

Enum based menus should be documented using the following syntax:

Menu Label
   General description of the menu.

   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.

Context Sensitive Manual Access¶

It is possible to link to a specific part of the manual from in Blender by right clicking on a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender's RNA tag. The easiest way to find out what the tag for a property is to right click on the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Ví Dụ về Mã Nguồn -- Code Samples¶

Nếu mình điền tên của ngôn ngữ lập trình vào nữa thì chức năng nêu bật cú pháp cho ngôn ngữ đó cũng sẽ hoạt động, nêu bật các dòng lên, đồng thời các số dòng cũng có thể được hiện lên nếu mình dùng tùy chọn :linenos: (số dòng):

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Hình Ảnh -- Images¶

Figure nên được sử dụng để đặt các hình ảnh minh họa:

.. figure:: /images/interface_splash_current.png

   Image caption.

Để nhất quán và để đảm bảo ảnh chụp màn hình có cùng kích thước tương tự khi đứng cạnh văn bản, tác giả nên chụp ảnh màn hình theo cách sau:

Chuẩn bị khu vực bạn muốn chụp hình và phải đảm bảo là mình sử dụng phong cách và sắp đặt mặc định. (Trong một số trường hợp, bạn có thể không muốn sử dụng cài đặt mặc định, ví dụ: nếu một số tùy chọn bị ẩn giấu đi sau một hộp kiểm (checkbox) chẳng hạn).
Phóng vào đến mức tối đa (bấm và giữ xuống Bàn Số + (NumpadPlus) hoặc Ctrl-NCG (MMB) hoặc tương tự).
Thu nhỏ tám lần (bấm phím kbd:Dấu Trừ (-) Bàn Số (NumpadMinus) tám lần).
Trong một số trường hợp, bạn có thể cần phải để lại một khoảng lề nhỏ xung quanh khoảng mà bạn muốn thu chụp. Phần lề này sẽ là rộng chừng 30 điểm ảnh, không cần chính xác lắm.

Cái này có thể chỉ áp dụng được trong một số phần của giao diện mà thôi, và có thể sẽ không áp dụng được trong mọi trường hợp.

Tập Tin -- Files¶

Không được sử dụng chữ hoa, không được để khoảng cách trống -- No Caps, No Gaps

Tên tập tin phải là chữ thường, dùng dấu gạch chân để tách biệt các từ (chẳng hạn tap_tin) .

Sắp Xếp Trật Tự Hợp Lý, Có Tác Dụng -- Sort Usefully

Đặt tên theo thứ tự, dùng các nhận dạng cụ thể nằm ở cuối.

Định Dạng -- Format

Sử dụng .png cho các hình ảnh có các màu cố định như ảnh chụp màn hình của giao diện Blender và .jpg cho hình ảnh có số lượng màu sắc biến đổi cao, chẳng hạn như các ví dụ kết xuất và các ảnh chụp.

Không sử dụng các tập tin .gif hoạt họa vì những tập tin này khó bảo trì và có thể gây mất tập trung, đồng thời chúng thường có kích thước tập tin lớn. Thay vào đó, hãy sử dụng một video nếu cần (xem phần về Video bên dưới).

Vị Trí -- Location

Đặt hình ảnh vào thư mục manual/images. Không sử dụng các thư mục nhánh khác.

Đặt Tên -- Naming

Để đặt tên các tập tin, hãy sử dụng dấu gạch chân để tách phân các chương và các phần riêng biệt, đồng thời sử dụng dấu gạch ngang để tách các phần có hai hoặc nhiều từ. Các tập tin hình ảnh sẽ trông giống thế này: chapter_subsection_sub-subsection_id.png, ví dụ:

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

Không được sử dụng các ký tự đặc biệt, hoặc các dấu cách trống!

Hướng Dẫn Sử Dụng -- Usage Guides¶

Tránh việc chỉ định độ phân giải của hình ảnh, hầu cho kiểu mẫu (theme) có thể xử lý hình ảnh một cách nhất quán và cung cấp bài trí tốt nhất cho các kích thước màn hình khác nhau.
Khi lập tài liệu cho một bảng hoặc một phần nào đó của giao diện người dùng, tốt hơn hết là nên sử dụng một hình ảnh hiển thị tất cả các khu vực liên quan (thay vì nhiều hình ảnh cho mỗi một biểu tượng hoặc mỗi một nút) và đặt nó ở đỉnh của phần bạn đang viết, rồi sau đó giải thích các tính năng theo thứ tự chúng xuất hiện trên hình ảnh.

Ghi chú

Bản hướng dẫn sử dụng sẽ phải được bảo quản trường kỳ, điều này rất quan trọng. Giao diện người dùng và các tùy chọn của công cụ rất hay thay đổi, vì vậy, hãy cố gắng tránh tình trạng có quá nhiều hình ảnh (đặc biệt là khi chúng không cần thiết). Nếu không, việc bảo quản sẽ trở nên một gánh nặng quá lớn.

Phim Video -- Videos¶

Videos from YouTube^™ can be embedded using:

.. youtube:: ID

Chỉ danh ID của phim sẽ nằm trong địa chỉ URL của phim video, chẳng hạn:

The ID for https://www.youtube.com/watch?v=Ge2Kwy5EGE0 is Ge2Kwy5EGE0.

Hướng Dẫn Sử Dụng -- Usage Guides¶

Tránh việc cho thêm các video có giọng nói, vì cái này rất khó phiên dịch.
Chớ gắn sẵn các video hướng dẫn như một phương tiện giải thích một tính năng của phần mềm. Bản thân nội dung của văn bản phải giải thích về nó đầy đủ (tuy nhiên, bạn có thể bao gồm một liên kết đến video ở dưới cùng của trang, dưới tiêu đề Trợ Lý Học Tập -- Tutorials).

Cấu Trúc Hữu Dụng -- Useful Constructs¶

|BLENDER_VERSION| -- Phân tích thành phiên bản hiện tại của Blender.
:abbr:`SSAO (Tính Hấp Thụ Quang Xạ Môi Trường (THTQXMT) Của Không Gian Màn Hình -- Screen Space Ambient Occlusion)` -- Các từ viết tắt hiển thị nội dung không viết tắt dưới dạng chú giải công cụ (để đầu chuột vào kết nối đó một lúc) cho người đọc nhìn thấy.
:term:`Đa Tạp -- Manifold` -- Liên kết đến một mục trong bảng Thuật Ngữ -- Glossary.

Đối Chiếu và Liên Kết -- Cross References and Linkage¶

Bạn có thể liên kết đến một tài liệu khác trong bản hướng dẫn sử dụng bằng dòng mã sau:

:doc:`The Title </section/path/to/file>`

Để liên kết đến một phần cụ thể nào đó trong một tài liệu khác (hoặc trong cùng một tài liệu), bạn có thể sử dụng các nhãn hiệu cụ thể như sau:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Kết nối với một tiêu đề nào đó trong cùng tập tin:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Kết nối với thế giới bên ngoài:

`Blender Website <https://www.blender.org>`__

Bố Trí của Thư Mục -- Directory Layout¶

Các phần nên được kết cấu một cách chung chung như sau:

directory_name/
- index.rst (có chứa các đường kết nối đến những tập tin nội bộ)
- introduction.rst
- section_1.rst
- section_2.rst

Ví dụ:

rendering/
- index.rst
- cycles/
  - index.rst
  - introduction.rst
  - materials/
    - index.rst
    - introduction.rst
    - volumes.rst

Đại ý là cần phải gộp tất cả các nội dung của một phần nội bên trong một thư mục. Lý tưởng nhất là mỗi phần cần có một bản index.rst (chứa TOC -- Mục Lục -- Table Of Content) -- cho phần đó và introduction.rst (giới thiệu) cho nội dung của phần đó.

Mục Lục -- Table of Contents¶

Theo mặc định, một bảng nội dung nên có hai tầng bậc:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Đọc Thêm -- Further Reading¶

Để học thêm về tái cấu trúc văn bản -- reStructuredText, xin xem:

Sphinx RST Primer: Giới thiệu cơ bản có chất lượng tốt.
Docutils reStructuredText Reference: Các đường kết nối đến những tham chiếu và tài liệu cho người dùng.