안내서 스타일 안내

../_images/33573755856_7f43d43adf_k_d.jpg

모든 문서가 그렇듯, 일관된 포맷을 갖추면 문서를 더 이해하기 쉬워집니다. 이 안내서를 더 잘 소화할 수 있도록, 모든 기여는 적절한 부분에서 이 스타일 안내의 규칙을 따라야 합니다.

이 안내서는 reStructuredText 로 작성되어 있습니다.

참고

안내서의 일부는 아직 이 스타일 안내와 일치하지 않을 수 있습니다. 그러한 부분을 안내서 스타일 안내에 맞게 자유롭게 갱신해 주세요.

참고

렌더링된 HTML의 어떤 페이지에서든 “Show Source”를 클릭하면 저자들이 페이지를 어떻게 스타일링했는지 볼 수 있습니다.

관련성

모든 기여가 안내서의 목적 과 관련성을 유지하도록 노력하세요.

  • 파이썬 개발과 직접 관련이 없는 주제에 대한 정보를 지나치게 많이 포함하지 마세요.

  • 정보가 이미 다른 곳에 있다면 다른 출처로 링크하는 편을 선호하세요. 무엇을, 왜 링크하는지 반드시 설명하세요.

  • 필요할 때 참조를 인용 하세요.

  • 주제가 파이썬과 직접 관련은 없지만 파이썬과 함께 쓰일 때 유용한 경우(예: Git, GitHub, 데이터베이스), 유용한 리소스로 링크하여 참조하고, 그것이 파이썬에 왜 유용한지 설명하세요.

  • 확신이 없다면 물어보세요.

헤딩

헤딩에는 다음 스타일을 사용하세요.

장(chapter) 제목:

#########
Chapter 1
#########

페이지 제목:

*******************
Time is an Illusion
*******************

섹션 헤딩:

Lunchtime Doubly So
===================

서브 섹션 헤딩:

Very Deep
---------

산문

텍스트 줄은 78자에서 줄바꿈하세요. 필요한 경우, 특히 줄바꿈하면 소스 텍스트가 더 읽기 어려워지는 경우에는 78자를 초과할 수도 있습니다.

영국식이 아닌 표준 미국식 영어를 사용하세요.

연속 콤마(serial comma) (옥스포드 콤마라고도 함)의 사용은 100% 필수입니다. 연속 콤마가 누락된 내용을 제출하려는 어떠한 시도라도, 완전하고 전적인 안목 부재를 이유로 이 프로젝트에서 영구 추방됩니다.

추방이라고요? 농담인가요? 부디 우리가 그것을 확인하게 되는 일은 없기를 바랍니다.

코드 예시

수평 스크롤바를 피하기 위해 모든 코드 예시는 70자에서 줄바꿈하세요.

커맨드라인 예시:

.. code-block:: console

    $ run command --help
    $ ls ..

Unix 콘솔 예시의 경우 각 줄 앞에 반드시 $ 접두사를 포함하세요.

Windows 콘솔 예시의 경우, console 대신 doscon 이나 powershell 을 사용하고, $ 접두사는 생략하세요.

파이썬 인터프리터 예시:

Label the example::

.. code-block:: python

    >>> import this

파이썬 예시:

Descriptive title::

.. code-block:: python

    def get_answer():
        return 42

외부 링크

  • 잘 알려진 주제(예: 고유명사)를 링크할 때는 라벨을 선호하세요:

    Sphinx_ is used to document Python.

.. _Sphinx: https://www.sphinx-doc.org

  • 맨 링크(bare link)를 그대로 두는 대신, 인라인 링크와 설명이 들어간 라벨을 함께 사용하는 편을 선호하세요:

    Read the `Sphinx Tutorial <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_

  • “여기 클릭”, “이것” 같은 라벨은 피하고, 설명이 잘 들어간(SEO에 좋은) 라벨을 사용하는 편을 선호하세요.

안내서 내의 섹션 링크하기

이 문서의 다른 부분을 상호 참조하려면, :ref: 키워드와 라벨을 사용하세요.

참조 라벨을 더 명확하고 고유하게 만들기 위해, 항상 -ref 접미사를 붙이세요:

.. _some-section-ref:

Some Section
------------

노트와 경고

메모를 작성할 때는 적절한 admonitions 디렉티브 를 활용하세요.

노트:

.. note::
    The Hitchhiker’s Guide to the Galaxy has a few things to say
    on the subject of towels. A towel, it says, is about the most
    massively useful thing an interstellar hitch hiker can have.

경고:

.. warning:: DON'T PANIC

할 일(TODO)

안내서의 미완성 부분은 todo 디렉티브 로 표시해 주세요. 할 일 목록 가 어수선해지는 것을 피하기 위해, 스텁 문서나 큰 미완성 섹션에는 todo 를 하나만 사용하세요.

.. todo::
    Learn the Ultimate Answer to the Ultimate Question
    of Life, The Universe, and Everything