마크업 스타일(markup style)

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

규칙

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

적당히만 지킬 규칙들

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

제목

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

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

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

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

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

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

주석

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

주석

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

글자 모야

overview on ReStructuredText 에 요소들의 모양(style)을 정하고 목록(list), 표(table), 이미지(picture), 코드블록(code block)을 추가하는 방법에 대한 더 자세한 내용이 있어요. Sphinx reference 에서는 그걸 사용하는 방법을 배울 수 있구요.

The following are useful markups for text styling:

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

화면(interface) 요소들

  • :kbd:`LMB` -- 키보드와 마우스 단축키
  • *Mirror* -- 화면의 이름(interface label)
  • :menuselection:`3D View --> Add --> Mesh --> Monkey` -- 메뉴

코드 샘플(code sample)

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

이미지

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

.. figure:: /images/render_cycles_nodes_types_shaders_node.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) 옵션은 때때로 바뀌니까 꼭 필요한 이미지 말고는 넣지 마세요. 이미지가 많아지면 사용설명서 유지보수 난이도가 엄청나게 올라가요.

비디오

YouTube™ 나 Vimeo™ 비디오는 이렇게 넣을 수 있어요.

.. youtube:: ID

.. vimeo:: ID

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

  • https://www.youtube.com/watch?v=Ge2Kwy5EGE0 의 ID는 Ge2Kwy5EGE0 이고
  • https://vimeo.com/15837189 의 아이디는 15837189 죠.

사용법

  • 말이 중요한 비디오는 되도록 넣지 마세요. 다른 언어 사람들이 알아듣기 어려우니까요.
  • 비디오를 튜토리얼의 의미로 넣지 마세요. 그건 글의 역할이에요. 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
참고 자료와 다른 문서들로 갈 수 있는 링크 모음