마크업 스타일(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 Elements

  • :kbd:`LMB` – 키보드와 마우스 단축키

  • *Mirror* – 화면의 이름(interface label)

  • :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – menus.

코드 샘플(code sample)

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

이미지

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

.. figure:: /images/interface_window-system_splash_current.png

   Image caption.

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

  1. 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.)

  2. 최대 확대율을 사용하세요. NumpadPlus 나 Ctrl-MMB 을 사용하면 돼요.

  3. 여덟 단계만큼 축소하세요. NumpadMinus 를 8번 누르면 돼요.

  4. 만약 찍고 싶은 대상의 바깥에 여백을 주어야 하는 상황이라면, 대략적으로 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 can be embedded from Blender’s self-hosted PeerTube instance which can be found at video.blender.org. To embed a video using the following directive:

.. peertube:: ID

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

The ID for https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c is 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

To get a new video uploaded, contact a Documentation Project Administrator or include the uploaded video in your Pull Request description.

사용법

  • Avoid adding videos that rely on voice or words, as this is difficult to translate.

  • Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately. (Though you may include a link to the video at the bottom of the page under the heading 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>`__

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of 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 open the context menu of 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
=========

Icons

Blender’s icons can be included as inline text using:

`:bl-icon:`<icon_name>`

읽을거리

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

Sphinx RST Primer

좋은 소개글

Docutils reStructuredText Reference

참고 자료와 다른 문서들로 갈 수 있는 링크 모음