2. 작성 지침

일반적으로, QGIS 프로젝트를 위한 reST 문서를 작성할 때 파이썬 문서 작성 스타일 지침서 를 따라주시기 바랍니다. 편의를 위해, 다음 부분에서 QGIS 문서 작성시 따라야 할 일반 규칙 모음을 소개합니다.

2.1. 문서 작성 

2.1.1. 표제 

문서의 .rst 파일 하나가 웹페이지 하나와 대응합니다.

밑줄(1단계 제목의 경우 윗줄도 포함) 그어진 제목을 통해 텍스트의 구조를 구성하는 절(section)을 식별합니다. 동일한 단계의 제목은 반드시 동일한 특수문자로 밑줄을 작성해야 합니다. QGIS 문서의 경우, 장(chapter), 절(section), 항(subsection), 목(minisec)에 대해 다음과 같은 스타일을 사용해야 합니다.

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. 목록 

목록은 텍스트를 구성하는 데 유용합니다. 모든 목록에 공통되는 간단한 규칙은 다음과 같습니다:

목록의 모든 항목을 대문자로 시작하십시오.
간단한 문장 한 줄만 담고 있는 목록 항목 뒤에 구두점을 찍지 마십시오.
복잡한 문장 하나 또는 문장 여러 개로 이루어진 목록 항목의 구두점으로 마침표( . )를 사용하십시오.

2.1.3. 들여쓰기 

ReStructuredText의 들여쓰기는 목록 또는 마크업 마커 와 정렬되어야 합니다. 들여쓰기로 블록 인용(block quotes)을 할 수도 있습니다. 들여쓰기 사양 을 참조하세요.

#. In a numbered list, there should be
   three spaces when you break lines
#. And next items directly follow

   * Nested lists
   * Are also possible
   * And when they also have
     a line that is too long,
     the text should be naturally
     aligned
   * and be in their own paragraph

However, if there is an unindented paragraph, this will reset the numbering:

#. This item starts at 1 again

2.1.4. 내부 처리 태그 

태그를 사용해서 항목을 강조할 수 있습니다.

메뉴 GUI : 일련의 완전한 메뉴 선택 순서를 표시합니다. 하위 메뉴를 선택해서 특정한 작업을 수행하는 순서, 또는 해당 순서의 하위 순서를 포함합니다.
```
:menuselection:`menu --> submenu`
```
대화창 및 탭 제목 : 창 제목, 탭 제목, 버튼 그리고 옵션 라벨을 포함하는 대화형 사용자 인터페이스의 일부로써 라벨을 표시합니다.
```
:guilabel:`title`
```
파일명 또는 디렉터리
```
:file:`README.rst`
```
팝업 텍스트를 가진 아이콘
```
|icon| :sup:`popup_text`
```
(다음 image 를 참조하십시오)
키보드 단축키
```
:kbd:`Ctrl+B`
```
Ctrl+B 와 같이 보일 겁니다.

키보드 단축키를 설명할 때, 다음과 같은 관례를 따라야 합니다:
- 문자 키는 대문자로 표시합니다: S
- 특수 키는 첫 문자를 대문자로 표시합니다: Esc
- 키 조합은 키 사이에 공백 없이 + 기호를 넣어 표시합니다: Shift+R
사용자 텍스트
```
``label``
```

2.1.5. 라벨/참조 

텍스트 안에 앵커(anchor)를 사용해서 절(section) 또는 페이지로 연결되는 하이퍼링크를 생성합니다.

다음은 절(예: 라벨/참조 제목)의 앵커를 생성하는 예시입니다.

.. _my_anchor:

Label/reference
---------------

동일 페이지 안에서 참조를 호출하려면 다음과 같이 작성합니다.

see my_anchor_ for more information.

다음과 같은 내용을 반환할 것입니다.

see my_anchor for more information.

‘앵커’ 가 가리키는 라인/객체로 넘어갈 것을 아시겠습니까? 아포스트로피를 쓸 필요는 없지만 앵커 다음에 반드시 빈 줄을 넣어야 합니다.

문서 어디에서든 동일한 장소로 넘어가는 또다른 방법은 :ref: 기능을 이용하는 것입니다.

see :ref:`my_anchor` for more information.

앵커 대신 캡션으로 (이 경우 현재 절의 제목으로) 링크를 생성할 것입니다:

see 라벨/참조 for more information.

이렇게 참조 1(my_anchor)과 참조 2(라벨/참조)라는 방법이 있습니다. 참조가 완전한 캡션을 표시하는 경우가 많기 때문에, 절 이라는 단어를 따로 작성할 필요는 없습니다. 또한 참조를 설명하는 데 사용자 지정 캡션을 쓸 수도 있습니다.

see :ref:`Label and reference <my_anchor>` for more information.

다음을 반환합니다:

see Label and reference for more information.

2.1.6. 도표와 이미지 

대체물 

텍스트 안에 이미지를 삽입할 수도 있고, 또는 다른 곳에서도 쓰기 위해 별명(alias)을 추가할 수도 있습니다. 문단 안에 이미지를 삽입하려면, 먼저 source/substitutions.txt 파일에 별명을 생성하십시오:

.. |nice_logo| image:: /static/common/logo.png
               :width: 1 em

그 다음 사용자의 문장에 별명을 호출하십시오:

My paragraph begins here with a nice logo |nice_logo|.

이 예시는 다음과 같이 표시될 것입니다:

My paragraph begins here with a nice logo .

깃허브에서 최대한 HTML 렌더링에 가까운 미리보기 렌더링을 가능하게 하려면, 사용자가 변경한 파일의 마지막에 이미지 대체물 호출도 추가해야 합니다. substitutions.txt 에서 복사-붙여넣기 하거나, scripts/find_set_subst.py 스크립트를 실행하면 됩니다.

참고

현재, 일관성을 보장하고 QGIS 아이콘 이용을 돕기 위해 별명 장에 사용자가 쓸 수 있는 별명 목록을 생성해 놓았습니다.

도형 

.. _figure_logo:

.. figure:: /static/common/logo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

결과는 다음과 같습니다:

그림 2.23 A caption: A logo I like

다른 참조와 충돌이 일어나는 것을 피하기 위해, 언제나 도형 앵커를 _figure_ 로 시작하고 도표 캡션과 쉽게 연관지을 수 있는 용어를 사용하십시오. 이미지에 대해서는 필수적으로 중앙 정렬만 사용해야 하지만, 필요한 경우 도형을 위한 다른 (width, height, scale 등등 같은) 옵션들은 자유롭게 사용해도 됩니다.

스크립트가 문서 생성시 HTML 및 PDF 버전에 있는 도형의 캡션 앞에 자동으로 생성된 번호를 삽입할 것입니다.

캡션을 쓰려면 (My caption 참조) .. figure:: 단락의 빈 줄 다음에 원하는 텍스트를 삽입하면 됩니다.

다음과 같이 참조 라벨을 사용해서 도형을 참조할 수 있습니다:

see :numref:`figure_logo`

다음과 같이 렌더링됩니다:

see 그림 2.23

도형을 참조하는 데에는 이 방법이 더 낫습니다.

참고

:numref: 가 제대로 작동하기 위해서는 도형이 캡션을 가지고 있어야만 합니다.

참조의 경우 :numref: 대신 :ref: 를 사용할 수도 있지만, :ref: 는 이미지 캡션 전체를 반환합니다.

see :ref:`figure_logo`

다음과 같이 렌더링됩니다:

see A caption: A logo I like

표 

간단한 테이블은 다음과 같이 코딩할 수 있습니다:

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
4                 5
=======  =======  =======

다음과 같이 렌더링될 것입니다:

x	y	z
1	2	3
4		5

공백을 남기려면 \ (백슬래시) 뒤에 공백을 삽입하십시오.

좀 더 복잡한 표를 만들어서 참조할 수도 있습니다:

.. _my_drawn_table:

+---------------+--------------------+
| Windows       | macOS              |
+---------------+--------------------+
| |win|         | |osx|              |
+---------------+--------------------+
| and of course not to forget |nix|  |
+------------------------------------+

My drawn table, mind you this is unfortunately not regarded as a caption

You can reference it like this: my_drawn_table_.

결과물은 다음과 같습니다:

Windows	macOS

and of course not to forget

My drawn table, mind you this is unfortunately not regarded as a caption

You can reference to it like this my_drawn_table.

더욱 복잡한 표를 원한다면, list-table 을 사용하는 편이 좋습니다:

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

   * - What
     - Purpose
     - Key word
     - Description
   * - **Test**
     - ``Useful test``
     - complexity
     - Geometry.  One of:

       * Point
       * Line

결과물은 다음과 같습니다:

What

Purpose

Key word

Description

Test

Useful test

complexity

Geometry. One of:

Point
Line

2.1.7. 색인 

색인(index)은 독자가 문서에서 정보를 손쉽게 찾을 수 있게 해주는 방법입니다. QGIS 문서는 몇몇 필수적인 색인들을 제공합니다. 활용성이 매우 높은 (알기 쉽고 일관적이며 서로 긴밀하게 연결되어 있는) 색인 집합을 제공할 수 있도록 해주는 규칙이 몇 개 있습니다:

색인은 사람이 읽고 이해하고 번역할 수 있어야 합니다. 색인은 많은 단어들로 이루어질 수 있지만, 단어들 사이를 불필요한 _, - 등의 문자들로 연결해서는 안 됩니다. 예를 들면 loading_layers 또는 loadingLayers 보다는 Loading layers 를 사용해야 합니다.
단어의 철자가 특별히 그렇게 되어 있는 경우를 제외하고, 색인의 첫 글자만 대문자로 쓰십시오. 예: Loading layers, Atlas generation, WMS, pgsql2shp.
올바른 철자로 된 가장 편리한 표현을 재사용하고 불필요한 중복을 피하기 위해, 기존 색인 목록 을 살펴보십시오.

RST에는 몇몇 색인 태그들이 있습니다. 일반 텍스트 안에서는 그때그때 즉시 처리되는(inline) :index: 태그를 사용하면 됩니다:

QGIS can load several :index:`Vector formats` supported by GDAL ...

또는 다음 문장의 시작 부분을 링크하는 블록 수준 마크업 .. index:: 를 사용해도 됩니다. 앞에서 언급한 규칙 때문에, 블록 수준 태그를 사용할 것을 권장합니다:

.. index:: WMS, WFS, Loading layers

single, pair 그리고 see 같은 색인 파라미터를 사용할 것도 권장합니다. 좀 더 구조화되고 상호 연결된 색인 테이블을 작성하기 위해서입니다. 인덱스 생성에 대해 더 자세히 알고 싶다면 색인 생성하기 를 참조하세요.

때때로, 사용자에게 경고하거나 상기시키거나 힌트를 주기 위해 설명의 몇몇 포인트를 강조하고 싶을 수도 있습니다. QGIS 문서에서는 .. warning::, .. seealso::`, ``.. note:: 그리고 .. tip:: 같은 reST 특별 지시어(special directive)를 사용합니다. 이 지시어들은 작성자의 언급 사항을 강조하는 프레임을 생성합니다. 자세한 내용은 문장 수준 마크업 을 참조하세요. 경고 및 힌트 둘 다 명료하고 적절한 제목이 반드시 필요합니다.

.. tip:: **Always use a meaningful title for tips**

   Begin tips with a title that summarizes what it is about. This helps
   users to quickly overview the message you want to give them, and
   decide on its relevance.

2.1.9. 코드 조각 

예를 들기 위해 코드 조각(code snippet)을 삽입하고 싶을 수도 있습니다. 이런 경우, 한 줄 아래에 :: 지시어를 삽입하고 코드를 작성하십시오. 더 나은 렌더링을 원한다면, 특히 코드 언어에 따라 색상 강조를 적용하고 싶다면, .. code-block:: xml 같은 코드 블록 지시어를 사용하십시오. 더 자세한 내용은 코드 표시하기 를 참조하세요.

참고

참고, 힌트 및 경고 프레임 안의 텍스트는 번역할 수 있지만, 코드 블록 프레임은 번역할 수 없다는 점을 주의하십시오. 즉 코드에 관련되지 않은 언급은 자제하고 가능한 한 짧게 작성해야 한다는 뜻입니다.

2.1.10. 주석 

어떤 번역 소프트웨어도 주석을 식별하지 못 하며, 또 주석은 PDF 포맷으로 제대로 변환되지도 않습니다. 따라서 가능하다면 어떤 문서에도 주석을 쓰지 마십시오.

다음은 주석을 생성하기 위한 문법입니다(이와 같이 표시됩니다 [1])

blabla [1]_

다음을 가리키게 됩니다.

2.2. 스크린샷 관리 

2.2.1. 새 스크린샷 추가 

보기 좋은 새 스크린샷을 생성하기 위한 힌트를 몇 개 드리겠습니다. 스크린샷이 참조하는 .rst 파일과 동일한 폴더 안에 있는 이미지 폴더(img/)에 스크린샷 이미지를 저장해야 합니다.

스크린샷을 캡처하기 위해 사용된 기존 QGIS 프로젝트 몇 개를 이 저장소의 ./qgis-projects 폴더에서 찾아볼 수 있습니다. QGIS 다음 버전에서 스크린샷을 다시 캡처하는 데 도움이 될 것입니다. 이 프로젝트들은 QGIS 샘플 데이터 (일명 알래스카 데이터셋)을 이용하는데, QGIS 문서 저장소와 동일한 폴더에 이 데이터셋을 압축 해제해야 합니다.
기능을 보여주는 데 필요한 최소한의 공간만 차지하도록 창 크기를 줄입니다. (작은 대화창을 화면 전체 크기로 캡처할 필요는 없겠죠.)
직관적이고 단순할수록 좋습니다. (모든 툴바를 활성화시킬 필요는 없습니다.)
스크린샷의 크기를 이미지 편집기로 조정하지 마십시오. 필요할 경우 .rst 파일 내부에서 이미지 크기를 설정하면 됩니다. (해상도를 제대로 높이지 않고 크기를 줄일 경우 보기에 안 좋은 이미지가 됩니다.)
배경을 잘라내십시오.
배경이 하얀색이 아닐 경우 상단 모서리를 투명하게 조정하십시오.
인쇄 해상도를 135 dpi 로 조정하십시오. 예를 들어 김프(GIMP)를 사용할 경우 Image ► Print size 메뉴에서 인쇄 해상도를 조정한 다음 저장하십시오. 이렇게 하면 이미지가 HTML에서는 원래 크기로, PDF에서는 훌륭한 인쇄 해상도로 나올 겁니다. 다음과 같이 ImageMagick 변환 명령어를 써서 여러 이미지들을 배치 작업할 수도 있습니다:
```
convert -units PixelsPerInch input.png -density 135 output.png
```
스크린샷을 .png 로 저장하십시오. (.jpeg 특허 침해를 피하기 위해서입니다.)
스크린샷은 텍스트가 설명하는 내용을 보여주어야 합니다.

팁

우분투를 사용한다면, 전체 수준 메뉴 기능을 제거해서 더 작은 응용 프로그램 스크린샷을 생성하려면 다음 명령어를 사용하십시오:

sudo apt autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

2.2.2. 스크린샷 번역 

번역된 사용자 지침서를 위한 스크린샷을 생성하길 원한다면 다음 규칙을 따르세요:

번역 이미지는 img/<your_language>/ 폴더에 있어야 합니다. 영어 ‘원본’ 스크린샷과 동일한 파일명으로 저장하십시오.

2.3. 공간 처리 알고리즘 문서 작성 

공간 처리 알고리즘을 위한 문서를 작성하고자 할 경우, 다음과 같은 지침들을 고려하십시오:

공간 처리 알고리즘 도움말 파일은 QGIS 사용자 설명서의 일부입니다. 따라서 사용자 지침서 및 기타 문서들과 동일한 서식을 이용하십시오.
각 알고리즘 문서는 그에 대응하는 제공자(provider) 폴더에 대응하는 그룹(group) 파일로 저장돼야 합니다. 예를 들어 Voronoi polygon 알고리즘은 QGIS 제공자와 vectorgeometry 그룹에 속해 있습니다. 따라서 설명을 추가해야 할 정확한 파일은 다음과 같습니다: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst

참고

지침서 작성을 시작하기 전에, 이미 해당 알고리즘을 설명하고 있는지 확인하십시오. 이미 설명되어 있다면, 기존 설명을 강화할 수 있습니다.
각 알고리즘이 제공자 이름과 알고리즘 자체의 유일한 이름에 대응하는 앵커(anchor) 를 가진다는 사실이 극히 중요합니다. 도움말 버튼이 도움말 페이지에서 정확한 부분을 열 수 있게 해주기 때문입니다. 이 앵커는 다음과 같이 제목 위에 배치시켜야 합니다(라벨/참조 도 참조하세요):
```
.. _qgisvoronoipolygons:

Voronoi polygons
----------------
```
알고리즘 이름을 알고 싶다면 공간 처리 툴박스에 있는 알고리즘 위에 마우스를 가져가기만 하면 됩니다.
알고리즘 설명의 첫 문장으로 “이 알고리즘은 이런 기능을 하고 저런 기능도…” 같은 문장을 피하십시오. 다음과 같이 좀 더 일반적인 표현을 사용하도록 하십시오:
```
Takes a point layer and generates a polygon layer containing the...
```
알고리즘 이름을 반복하며 알고리즘의 기능을 설명하지 마세요. 특히 파라미터 자체를 설명할 때 파라미터 이름을 반복하지 마십시오. 예를 들어 알고리즘이 Voronoi polygon 일 경우 입력 레이어 를 폴리곤을 계산할 레이어 라고 설명하는 편이 좋습니다.
알고리즘 설명에서 해당 알고리즘이 QGIS에서 단축키를 가지는지 또는 제자리(in-place) 편집 작업을 지원하는지 명시하십시오.
이미지를 추가하십시오! 백문이 불여일견입니다! .png 포맷을 사용하고 문서를 위한 일반 지침을 따르십시오. (더 자세한 내용은 도표와 이미지 를 참조하세요.) 정확한 폴더에 이미지 파일을 저장하십시오. 예를 들어 작성자가 편집중인 .rst 파일이 있는 폴더의 img 폴더에 이미지를 저장해야 합니다.
필요한 경우, 알고리즘에 대한 추가 정보를 제공하는 “참조(See also)” 부분에 (예를 들면 출판물 또는 웹페이지를 가리키는) 링크를 추가하십시오. 정말로 참조해야 할 내용이 있을 경우에만 “참조” 부분을 추가하십시오. “참조” 부분을 비슷한 알고리즘들을 가리키는 링크들로 채우는 것도 좋은 방법입니다.
알고리즘 파라미터와 산출물에 대한 명확한 설명을 하십시오: 기존 알고리즘들을 참고하세요.
알고리즘 옵션의 자세한 설명을 복제하지 마십시오. 파라미터 설명에 이 정보를 추가하세요.
알고리즘 또는 파라미터 설명에 벡터 도형 유형 정보를 추가하지 마십시오. 이미 파라미터 설명에서 해당 정보를 볼 수 있습니다.

파라미터의 기본값을 다음과 같이 추가하십시오:

* - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [number]

    Default: 1
  - Number of points to create

파라미터가 지원하는 입력 유형 을 설명하십시오. 다음 몇몇 유형들 가운데 하나를 고를 수 있습니다:

파라미터/산출물 유형	Description	시각 지표
포인트 벡터 레이어	`vector: point`
라인 벡터 레이어	`vector: line`
폴리곤 벡터 레이어	`vector: polygon`
일반 벡터 레이어	`vector: any`
벡터 필드 숫자	`tablefield: numeric`
벡터 필드 문자열	`tablefield: string`
벡터 필드 일반	`tablefield: any`
래스터 레이어	`raster`
래스터 밴드	`raster band`
HTML 파일	`html`
테이블 레이어	`table`
표현식	`expression`
포인트 도형	`coordinates`
범위(extent)	`extent`
좌표계	`crs`
열거 목록(enumeration)	`enumeration`
목록	`list`
숫자	`number`
문자열	`string`
불(Boolean)	`boolean`
파일 경로	`folder`
파일	`file`
매트릭스	`matrix`
레이어	`layer`
입력 유형과 동일한 산출 유형	`same as input`
정의	`definition`
Point	`point`
다중레이어(MultipleLayer)	`multipleLayers`
범위(range)	`range`
인증환경설정(AuthConfig)	`authconfig`
메시(mesh)	`mesh`
조판(layout)	`layout`
조판항목(LayoutItem)	`layoutitem`
색상	`color`
축척	`scale`

기존에 잘 문서화된 알고리즘을 공부해서 유용한 모든 조판을 복사하십시오.
작성을 완료하면, 단계별 공헌 방법 에서 설명하는 지침을 따라 작성자의 변경 사항을 커밋하고 PR(Pull Request)을 생성하면 됩니다.

다음은 작성자에게 도움이 될 조판과 설명을 담고 있는 기존 알고리즘 의 예시입니다:

.. _qgiscountpointsinpolygon:

Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
point layer in each of the polygons of the polygon layer.
A new polygon layer is generated, with the exact same content as the input
polygon layer, but containing an additional field with the points count
corresponding to each polygon.

.. figure:: img/count_points_polygon.png
  :align: center

  The labels in the polygons show the point count

An optional weight field can be used to assign weights to each point.
Alternatively, a unique class field can be specified. If both options
are used, the weight field will take precedence and the unique class field
will be ignored.

``Default menu``: :menuselection:`Vector --> Analysis Tools`

Parameters
..........

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

   * - Label
     - Name
     - Type
     - Description
   * - **Polygons**
     - ``POLYGONS``
     - [vector: polygon]
     - Polygon layer whose features are associated with the count of
       points they contain
   * - **Points**
     - ``POINTS``
     - [vector: point]
     - Point layer with features to count
   * - **Weight field**

       Optional
     - ``WEIGHT``
     - [tablefield: numeric]
     - A field from the point layer.
       The count generated will be the sum of the weight field of the
       points contained by the polygon.
   * - **Class field**

       Optional
     - ``CLASSFIELD``
     - [tablefield: any]
     - Points are classified based on the selected attribute and if
       several points with the same attribute value are within the
       polygon, only one of them is counted.
       The final count of the points in a polygon is, therefore, the
       count of different classes that are found in it.
   * - **Count field name**
     - ``FIELD``
     - [string]

       Default: 'NUMPOINTS'
     - The name of the field to store the count of points
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]

       Default: [Create temporary layer]
     - Specification of the output layer type (temporary, file,
       GeoPackage or PostGIS table).
       Encoding can also be specified.

Outputs
.......

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

   * - Label
     - Name
     - Type
     - Description
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]
     - Resulting layer with the attribute table containing the
       new column with the points count