스핑크스 RST 스타일 지침

이 페이지는 스핑크스(Sphinx) 및 RST(reStructuredText)를 사용하기 위한 문법 규칙, 도움말, 그리고 꼼수를 담고 있습니다. 더 자세한 정보를 원한다면 이 reStructuredText에 대한 종합 지침서 는 물론 스핑크스 reStructuredText 입문서 를 읽어보십시오.

기본 마크업

RST 문서는 평문 텍스트로 작성됩니다. 복잡한 서식을 사용할 필요가 없기 때문에, 일반 텍스트 문서와 마찬가지로 간단하게 작성할 수 있습니다. 기본 서식에 대해서는 다음 표를 참조하십시오:

서식	문법	출력
이탤릭체	`italics` (별표 하나)	italics
볼드체	`bold` (별표 2개)	bold
고정폭 글꼴	`` `monospace` `` (억음 부호 2개)	`monospace`

Warning

기본 마크업 사용을 권장하지 않습니다! 가능한 경우 스핑크스의 그때 그때 즉시 처리하는(inline) 지시어를 사용해서 명령어, 파라미터, 옵션, 입력 및 파일을 표시하십시오. 지시어를 일관적으로 사용하면 이런 항목들에 스타일을 적절하게 지정할 수 있습니다.

목록

글머리 기호 목록(bulleted list)과 번호 매기기 목록(numbered list), 두 가지 유형의 목록이 있습니다. 글머리 기호 목록 은 다음과 같은 모양입니다:

한 항목
또다른 항목
또 하나의 항목

다음 코드를 이용해서 이런 목록을 만들 수 있습니다:

* 한 항목
* 또다른 항목
* 또 하나의 항목

번호 매기기 목록 은 다음과 같은 모양입니다:

첫 번째 항목
두 번째 항목
세 번째 항목

다음 코드를 이용해서 이런 목록을 만들 수 있습니다:

#. 첫 번째 항목
#. 두 번째 항목
#. 세 번째 항목

번호가 자동으로 생성되기 때문에 항목들을 쉽게 추가/제거할 수 있다는 사실을 기억하십시오.

목록 표

글머리 기호 목록이 길고 복잡해서 이해하기 어려운 경우가 가끔 있습니다. 긴 항목 목록을 다루는 경우 목록 표(list-table)를 사용하십시오. 예를 들어 옵션 목록에 관해 서술하는 경우 다음과 같은 모양의 표를 생성하십시오:

형태	설명
정사각형	네 변의 길이가 동일하고 각 변은 90도로 만납니다.
직사각형	네 변이 모두 90도로 만납니다.

이 표는 다음 코드로 만들어집니다:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - 형태
     - 설명
   * - 정사각형
     - 네 변의 길이가 동일하고 각 변은 90도로 만납니다.
   * - 직사각형
     - 네 변이 모두 90도로 만납니다.

페이지 라벨

모든 페이지에 파일명과 일치하는 라벨을 작성했는지 확인하십시오. 예를 들면 페이지 파일명이 foo_bar.rst 라면 페이지에 다음 라벨을 작성해야 합니다:

..  _foo_bar:

그러면 다른 페이지에서 다음 코드로 해당 페이지를 링크할 수 있습니다:

:ref:`foo_bar`

링크

다른 페이지를 가리키는 링크에 절대로 “여기”라는 제목을 붙여서는 안 됩니다. 스핑크스는 링크된 문서의 제목을 자동적으로 삽입해서 이를 쉽게 만들어줍니다.

나쁨: 링크에 관한 자세한 정보는 여기 에서 찾아볼 수 있습니다.
좋음: 더 자세한 정보를 알고 싶다면 링크 단락을 읽어보십시오.

외부 웹사이트를 가리키는 링크를 삽입하려면:

`링크 제목 <http://example.com>`__

그러면 다음과 같은 모양의 링크를 출력할 것입니다: 링크 제목

Warning

서로 다른 주소를 가리키지만 동일한 제목을 가진 링크 2개를 작성하는 실수를 쉽게 범할 수 있습니다. 이 경우 다음과 같은 오류가 발생합니다:

**(WARNING/2) Duplicate explicit target name:foo**

이런 경고를 피하려면 __ 를 이중으로 사용해서 익명 링크를 생성하십시오.

단락

단락을 이용해서 긴 페이지를 나누고 스핑크스가 목차를 생성할 수 있게 하십시오.

================================================================================
문서 제목
================================================================================

제1 수준
--------

제2 수준
++++++++

제3 수준
********

제4 수준
~~~~~~~~

메모 및 경고

본문으로부터 두드러지는 텍스트 단락을 작성하면 좋은 경우, 스핑크스에는 메모(note) 및 경고(warning)라는 글상자 2개가 있습니다. 기능은 동일하며, 색상만 다릅니다. 하지만 모든 것에 강조를 추가하면 강조의 효과가 떨어지기 때문에 메모 및 경고를 너무 자주 사용해서는 안 됩니다.

다음은 메모의 예시입니다:

Note

이것은 메모입니다.

다음 코드로 이 메모를 생성합니다:

.. note:: 이것은 메모입니다.

마찬가지로 다음은 경고의 예시입니다:

Warning

용을 조심하십시오.

다음 코드로 이 경고를 생성합니다:

.. warning:: 용을 조심하십시오.

이미지

가능한 경우 문서에 이미지를 추가하십시오. 화면 캡처 같은 이미지는 문서를 이해하기 쉽게 만들어주는 매우 유용한 방법입니다. 화면을 캡처하는 경우 필요없는 내용(탐색기 창, 배경화면 등등)을 잘라내십시오. 스핑크스가 큰 이미지를 자동으로 크기 조정하기 때문에 이미지 크기를 바꿀 필요는 없습니다. 이미지 아래에 캡션을 포함시키는 것도 도움이 됩니다:

.. figure:: image.png
   :align: center

   *캡션*

이 예시에서는 이미지 파일이 소스 페이지와 동일한 디렉터리에 존재합니다. 그렇지 않을 경우, 앞의 지시문에 경로 정보를 삽입하면 됩니다. 루트 / 가 conf.py 파일의 디렉터리입니다.:

.. figure:: /../images/gdalicon.png

외부 파일

텍스트 조각, 다운로드할 수 있는 코드의 큰 덩어리, 그리고 ZIP 파일 또는 다른 바이너리 소스조차 모두 문서의 일부분으로 포함시킬 수 있습니다.

샘플 파일을 가리키는 링크를 포함시키려면 download 지시어를 사용하십시오:

:download:`외부 파일 <example.txt>`

이 코드는 외부 파일 을 가리키는 표준 링크를 생성할 것입니다.

파일의 내용을 포함시키려면 literalinclude 지시어를 사용하십시오:

:command:`gdalinfo` 사용의 예시:

.. literalinclude:: example.txt

gdalinfo 사용의 예시:

Driver: GTiff/GeoTIFF
Size is 512, 512
Coordinate System is:
PROJCS["NAD27 / UTM zone 11N",
    GEOGCS["NAD27",
        DATUM["North_American_Datum_1927",
            SPHEROID["Clarke 1866",6378206.4,294.978698213901]],
        PRIMEM["Greenwich",0],
        UNIT["degree",0.0174532925199433]],
    PROJECTION["Transverse_Mercator"],
    PARAMETER["latitude_of_origin",0],
    PARAMETER["central_meridian",-117],
    PARAMETER["scale_factor",0.9996],
    PARAMETER["false_easting",500000],
    PARAMETER["false_northing",0],
    UNIT["metre",1]]
Origin = (440720.000000,3751320.000000)
Pixel Size = (60.000000,-60.000000)
Corner Coordinates:
Upper Left  (  440720.000, 3751320.000) (117d38'28.21"W, 33d54'8.47"N)
Lower Left  (  440720.000, 3720600.000) (117d38'20.79"W, 33d37'31.04"N)
Upper Right (  471440.000, 3751320.000) (117d18'32.07"W, 33d54'13.08"N)
Lower Right (  471440.000, 3720600.000) (117d18'28.50"W, 33d37'35.61"N)
Center      (  456080.000, 3735960.000) (117d28'27.39"W, 33d45'52.46"N)
Band 1 Block=512x16 Type=Byte, ColorInterp=Gray

literalinclude 지시어에 문법 강조, 줄 번호 및 조각 추출을 위한 옵션을 사용할 수 있습니다:

Example of :command:`gdalinfo` use:

.. literalinclude:: example.txt
   :language: txt
   :linenos:
   :emphasize-lines: 2-6
   :start-after: Coordinate System is:
   :end-before: Origin =

참조 파일 및 경로

파일 및 경로를 참조하려면 다음 문법을 사용하십시오:

:file:`myfile.txt`

이 코드는 다음을 출력할 것입니다: myfile.txt.

경로도 동일한 방법으로 참조할 수 있습니다:

:file:`path/to/myfile.txt`

이 코드는 다음을 출력할 것입니다: path/to/myfile.txt.

윈도우 경로의 경우, 이중 역슬래시를 사용하십시오:

:file:`C:\\myfile.txt`

이 코드는 다음을 출력할 것입니다: C:\myfile.txt.

특정하지 않은 경로 또는 파일명을 참조하고자 하는 경우:

:file:`{your/own/path/to}/myfile.txt`

이 코드는 다음을 출력할 것입니다: your/own/path/to/myfile.txt

코드 참조

클래스를 참조하려면:

:cpp:class:`MyClass`

메소드 또는 함수를 참조하려면:

:cpp:func:`MyClass::MyMethod`
:cpp:func:`MyFunction`

환경설정 옵션 참조

GDAL_CACHEMAX 같은 환경설정 옵션을 참조하려면 다음 코드를 사용하십시오:

:decl_configoption:`OPTION_NAME`

명령어 참조

다음 문법을 사용해서 (gdalinfo 같은) 명령어를 참조하십시오:

:program:`gdalinfo`

명령줄 옵션에는 option 지시어를 사용하십시오:

.. option:: -json

   산출물을 JSON 서식으로 출력합니다.

생성 파라미터를 문서화하려면 describe 지시어를 사용하십시오:

.. describe:: WORLDFILE=YES

   관련 ESRI 월드 파일을 (.wld 확장자로) 강제 생성합니다.