마크업 스타일(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_principled_node.png

   Image caption.

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

  1. 기본 테마(theme)와 설정을 사용하세요.

  2. 최대 확대율을 사용하세요. NumpadPlusCtrl-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

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