마크업 스타일(markup style)¶

이 페이지는 reStructuredText(RST) 마크업 언어로 작성할 때 지킬 규칙에 대해서 대해서 다루고 있어요.

규칙¶

세 칸 들여쓰기(three space indentation)
한 줄에 120글자 이하
버튼이랑 메뉴 이름에는 기울임 글꼴(italics) 쓰기

적당히만 지킬 규칙들

유니코드 문자는 사용 자제하기
텍스트를 너무 감싸지 않기

제목¶

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

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

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

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

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

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

참고

Parts 는 내용이나 색인에만 쓰여야 합니다.

참고

각 .rst 파일은 단 하나의 제목(heading) (*) 만 가져야 합니다..

글자 모야¶

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.

The following are useful markups for text styling:

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

화면(interface) 요소들¶

:kbd:`LMB` – 키보드와 마우스 단축키
*Mirror* – 화면의 이름(interface label)
: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
=========

코드 샘플(code sample)¶

구문 강조에 대한 지원이 있고, 줄 번호도 :linenos: 으로 나타낼 수 있어요.

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

이미지¶

이미지를 넣는 데에는 figure가 쓰여요.

.. figure:: /images/interface_splash_current.png

   Image caption.

글자 옆에 이미지가 삽입될 때 그 크기나 내용은 일관적이어야 하니까, 기여자님들은 스크린샷을 이렇게 찍어주세요.

Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)
최대 확대율을 사용하세요. NumpadPlus 나 Ctrl-MMB 을 사용하면 돼요.
여덟 단계만큼 축소하세요. NumpadMinus 를 8번 누르면 돼요.
만약 찍고 싶은 대상의 바깥에 여백을 주어야 하는 상황이라면, 대략적으로 30픽셀만큼 테두리를 주세요.

약간의 예외 말고는 언제나 적용될 규칙들이에요.

파일¶

대문자, 띄어쓰기는 노노

항상 소문자랑 밑줄(_)을 사용하세요.

효율적으로 정리하기

끝에 식별자(identifier)를 넣어서 순서를 정리하세요.

형식(format)

블렌더 화면 등 단색을 많이 가지고 있으면 .png 를 쓰고, 렌더 이미지나 사진처럼 복잡한 색깔들이 많이 쓰이면 .jpg 를 사용해 주세요.

움직이는 .gif 파일은 관리하기 힘들고 산만하니까 쓰지 마세요. 그 대신 비디오를 사용하면 돼요. 밑의 Videos 챕터에 설명이 더 잘 나와 있어요.

위치

이미지는 manual/images 폴더에 넣어 주세요. 하위 폴더는 쓰지 마세요.

이름

밑줄(_)로 챕터를 구분하고, 하이픈(-)으로 띄어쓰기가 포함된 제목의 단어를 구분하세요. 예를 들어 이미지 파일 이름은 chapter_subsection_sub-subsection_id.png 게 되겠죠.

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

특수문자나 띄어쓰기는 쓰면 안 돼요!

사용법¶

이미지의 해상도를 지정하지 마세요. 그래야 일관되고 다양한 화면 크기에서도 보기 좋으니까요.
화면(UI)의 패널(panel)이나 부분(section)에 대해 적을 때는, 관련된 모습을 한꺼번에 보여주는 하나의 이미지를 사용하는 게 좋아요. 아이콘 따로, 버튼 따로 보여주지 마세요. 그리고 이미지에서 나온 순서대로 설명도 적어주세요.

참고

사용설명서는 꾸준히 유용하게 쓰여야 하고, 그와 반대로 화면(UI)와 도구(tool) 옵션은 때때로 바뀌니까 꼭 필요한 이미지 말고는 넣지 마세요. 이미지가 많아지면 사용설명서 유지보수 난이도가 엄청나게 올라가요.

비디오¶

Videos from YouTube^™ can be embedded using:

.. youtube:: ID

``ID``는 비디오의 ``URL``에서 확인할 수 있답니다. 예를 들면 이래요.

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

사용법¶

말이 중요한 비디오는 되도록 넣지 마세요. 다른 언어 사람들이 알아듣기 어려우니까요.
비디오를 튜토리얼의 의미로 넣지 마세요. 그건 글의 역할이에요. Tutorials 이라는 이름으로 페이지 맨 밑에 링크를 넣는 건 괜찮아요.

유용한 기능¶

현재 블렌더 버전을 보여줘요.
생략(abbreviation)은 그 텍스트를 툴팁으로 보여줘요.
:term:`Manifold` – 는 </glossary/index> 에서 그 단어를 찾을 수 있는 링크에요.

다른 문서로 가는 링크¶

이렇게 다른 문서로 링크를 걸 수 있어요.

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

이 문서나 다른 문서의 특정 섹션(section)으로 가고 싶다면, 명시할 수 있어요.

.. _sample-label:

[section or image to reference]

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

같은 문서의 다른 부분으로 링크를 걸 수도 있어요.

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

Body text.

Implicit references, like `Titles are Targets`_

이렇게 하면 사용설명서를 탈출할 수도 있죠.

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

폴더 구조¶

섹션(secion)은 이렇게 정리되어야 해요.

directory_name/
- index.rst (contains links to internal files)
- introduction.rst
- section_1.rst
- section_2.rst

예를 들어 이렇게 되죠.

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

섹션 내용은 모두 폴더 안에 들어가게 돼요. 모든 섹션은 index.rst 목차 파일이랑 introduction.rst 소개 파일을 가져요.

목차¶

목차는 두 단계의 깊이(depth)를 가져야 해요.

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

읽을거리¶

reStructuredText에 대해 더 배우려면 이곳을 찾아가 보세요.

Sphinx RST Primer: 좋은 소개글
Docutils reStructuredText Reference: 참고 자료와 다른 문서들로 갈 수 있는 링크 모음

Join the 2%

마크업 스타일(markup style)¶

규칙¶

제목¶

글자 모야¶

화면(interface) 요소들¶

Operator Menus¶

Panels¶

Properties¶

Context Sensitive Manual Access¶

코드 샘플(code sample)¶

이미지¶

파일¶

사용법¶

비디오¶

사용법¶

유용한 기능¶

다른 문서로 가는 링크¶

폴더 구조¶

목차¶

읽을거리¶