문서 작성 스타일 가이드¶

이 가이드에는 새 콘텐츠 작성 및 기존 콘텐츠 번역과 관련하여 예상되는 스타일, MkDocs 전용 구문, 다양한 필수 도구, 문서 번역에 대한 정보가 포함되어 있습니다.

일반적인 스타일¶

헤더와 제목은 첫 단어만 대문자로 표기해야 합니다.
미국식 철자를 선호하며, 프로그래밍 특유의 관용 표현(예: "apps")과 명사의 동사화(예: "scrollable")에 대해서는 일부 유연성을 허용합니다.
"artefact"와 "artefacts"의 철자는 표시된 대로입니다.
우리는 마침표 뒤에 한 칸의 공백을 사용합니다.
우리는 공백으로 둘러싸인 단일 하이픈을 엠 대시(또는 HTML — 리터럴)로 사용합니다.
제품명에 대한 모든 언급은 해당 제품의 권장 대소문자 표기법을 사용해야 합니다. (예: "macOS", "GTK", "pytest", "Pygame", "PyScript").
어떤 용어가 "암호화된 표현"으로 사용되고 있다면, 해당 용어는 사전 항목으로 추가하기보다는 인라인 코드로 인용해야 합니다. 이를 위해서는 해당 용어를 단일 백틱(`)으로 감싸야 합니다.
사용자가 취해야 할 행동을 설명할 때 "단순히", "그냥", "쉽게"와 같은 표현은 사용하지 않습니다. 이러한 표현은 특히 사용자가 어려움을 겪고 있을 때 부정적인 뉘앙스로 받아들여질 수 있습니다.

교차 참조 정보¶

문서에서 가능한 경우 항상 내용을 상호 참조해야 합니다. 이 섹션에서는 참조하는 정보의 유형에 따라 적용할 수 있는 다양한 방법을 다룹니다.

MkDocs는 표준 마크다운 형식의 링크를 렌더링합니다. 표준 마크다운 형식의 웹 하이퍼링크는 다음과 같습니다:

[Link text](https://example.com/)

이 형식을 사용하여 로컬 파일에 링크할 수도 있습니다:

[Link text](path/to/file.md)

파일의 특정 섹션이나 API 문서를 참조하려면 MkDocs 참조 링크 형식을 사용해야 합니다.

사용자 정의 마크다운 앵커 및 콘텐츠 상호 참조¶

마크다운은 모든 헤더(한 줄에 1개에서 6개 사이의 # 기호로 시작하는 모든 내용)에 대해 헤더 내용에 기반한 앵커를 생성합니다. 예를 들어, 이 섹션에 대해 생성된 앵커는 custom-markdown-anchors-and-content-cross---referencing입니다. 그러나 당사 번역 방식의 특성상, 섹션 헤더가 참조될 때마다 반드시 사용자 정의 앵커를 가져야 합니다.

MkDocs는 수정된 마크다운 링크를 사용하여 문서 내 다양한 다른 요소로 연결할 수 있는 참조 링크 구문 렌더링을 지원합니다. 여기에는 사용자 정의 마크다운 헤더 및 텍스트 앵커로의 링크 등이 포함됩니다.

MkDocs 참조 링크는 다음과 같이 형식화된 모든 링크입니다:

[Link text][link-target]

사용자 정의 헤더 및 콘텐츠 앵커가 필요합니다

BeeWare 문서에서 MkDocs 참조 링크를 통해 텍스트 콘텐츠에서 참조되는 모든 헤더 또는 콘텐츠 섹션에는 반드시 사용자 정의 앵커가 첨부되어야 합니다. 그렇지 않으면 헤더 콘텐츠가 번역될 때 링크가 깨질 가능성이 있습니다.

헤더 앵커로 연결해야 하는 경우, 해당 콘텐츠에 대한 사용자 지정 앵커를 생성해야 합니다. 사용자 지정 앵커를 설정하는 일반적인 구문은 다음과 같습니다:

# Header text { #anchor-name }

예를 들어, 이 섹션의 앵커를 custom-anchors로 맞춤 설정하려면 다음과 같은 서식으로 처리합니다:

## Custom Markdown anchors { #custom-anchors }

일반 콘텐츠(텍스트 및 코드 블록 포함)에도 앵커를 생성할 수 있습니다. 링크를 설정하려는 콘텐츠 상단에 다음 서식을 포함해야 합니다. 서식에는 상하에 줄바꿈이 포함되어야 합니다:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

사용자 정의 앵커가 생성되면 동일한 문서 내에서 또는 문서의 다른 부분에서 해당 앵커로 연결할 수 있습니다.

표준 마크다운은 동일한 파일 내의 앵커로 연결하는 데 사용되며, 다음과 같이 형식화됩니다:

[Link text](#anchor-name)

다른 문서의 앵커에 링크하는 것은 MkDocs 참조 링크 스타일을 사용하며, 다음과 같이 형식화됩니다:

[Link text][anchor-name]

API 참조 링크¶

MkDocs 참조 링크 기능은 문서화된 클래스, 클래스 메서드 또는 속성을 포함한 API 문서와 특정 외부 문서 참조 간의 상호 참조도 지원합니다.

문서화된 클래스나 클래스 메서드, 속성에 링크하는 방법은 여러 가지가 있으며, 동일한 파일에서 링크하든 별도의 파일에서 링크하든 상관없습니다. 클래스 등에 링크할 때는 이름을 인라인 코드로 렌더링하기 위해 첫 번째 대괄호 안에 백틱(`)을 포함해야 합니다. 백틱은 인라인 코드로 렌더링되지 않아야 하는 사용자 정의 텍스트를 사용하는 경우에만 생략할 수 있습니다. 두 번째 대괄호에는 백틱을 절대 포함해서는 안 됩니다.

네임스페이스를 표시하면서 클래스에 링크하는 형식은 다음과 같습니다:

[`module.ClassName`][]

클래스 이름만 표시하면서 클래스에 연결하는 형식은 다음과 같습니다:

[`ClassName`][module.ClassName]

속성은 위와 동일하며, 속성 이름이 포함됩니다. 다음은 네임스페이스를 표시합니다:

[`module.ClassName.attributename`][]

클래스와 마찬가지로 속성 이름만 표시하는 형식은 다음과 같습니다:

[`attributename`][module.ClassName.attributename]

메서드는 네임스페이스 뒤에 ()로 표시되어야 하므로, 속성과는 다르게 처리해야 합니다. 메서드에 연결하는 적절한 방법은 다음과 같습니다:

[`module.ClassName.methodname()`][module.ClassName.methodname]

다음은 클래스와 메서드 이름만 표시합니다. 또한 이름 뒤에 괄호를 포함해야 합니다:

[`Classname.methodname()`][module.Classname.methodname]

적용 가능한 네임스페이스와 동일한 메서드를 사용하여 임의의 텍스트를 표시하면서 클래스, 메서드 또는 속성에 링크할 수 있습니다. 클래스에 대해 이 작업을 수행하는 형식은 다음과 같습니다:

[link text][module.ClassName]

파이썬 핵심 문서 및 Pillow 문서로도 직접 링크할 수 있습니다. 예를 들어, int 문서로 링크하려면:

[`int`][]

Pillow Image 문서에 연결하려면:

[`PIL.Image.Image`][]

코드 블록 팁¶

언어 및 코드 강조 표시¶

코드블록 내부에 포함된 코드의 언어를 지정하려면 첫 세 개의 백틱 뒤에 공백 없이 언어 이름을 포함시키면 됩니다. 이렇게 하면 코드가 렌더링될 때 적절한 코드 강조 표시가 적용됩니다. 예를 들어 Python을 지정하려면 코드블록을 ```python로 시작하면 됩니다.

콘솔 명령어와 복사 버튼¶

콘솔 명령어나 출력 명령어를 포함하는 경우, Unix 계열(macOS 포함) 운영체제를 설명하는지 Windows를 설명하는지에 따라 console 또는 doscon로 표시하십시오. 운영체제에서 제공하는 프롬프트를 포함할 수 있으며, 복사 버튼을 클릭하면 명령어만 복사됩니다. 예를 들어, 코드 블록을 ```console로 시작하고 다음과 같은 내용을 포함하는 경우:

$ mkdir test
$ ls
test

그런 다음 코드 블록의 복사 버튼을 클릭하면 명령어만 복사되고 프롬프트와 출력은 무시됩니다. 이를 통해 콘솔 명령어임을 표시하면서도 사용자가 복사 버튼을 효과적으로 사용할 수 있게 합니다.

특정 코드 줄 강조 표시¶

특정 코드 줄을 강조 표시할 수 있습니다. 예를 들어, 2번째 줄을 강조하려면 언어 뒤에 공백을 추가한 다음 {hl_lines="2"}를 붙입니다. 따라서 코드 블록은 ```python {hl_lines="2"}로 시작하게 됩니다. 결과는 다음과 같습니다:

import toga
from toga.style.pack import COLUMN, ROW

여러 개의 서로 다른 줄을 강조 표시할 수 있습니다. 예를 들어, python {hl_lines="3 5 9"}는 3, 5, 9번 줄을 강조 표시합니다. 일련의 줄을 강조 표시할 수도 있습니다. 예를 들어, python {hl_lines="3-8"}는 3번부터 8번 줄까지를 강조 표시합니다. 여러 개의 범위를 강조 표시할 수 있습니다. 예를 들어, python {hl_lines="9-18 23-44"}로 여러 범위를 지정할 수 있습니다.

특정 서식이 필요한 마크다운 요소¶

번역 파일 생성 방식상, 경고문, 주석, 탭, Jinja 지시어, 이미지 캡션 및 정렬 등에 필요한 개행은 Markdown 구문에 반드시 포함해야 합니다.

경고와 주의사항¶

경고문은 다음과 같이 서식을 지정해야 하며, 경고문 시작과 끝 부분 앞뒤에 반드시 줄바꿈을 포함해야 합니다:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

이것은 지원되는 모든 경고 유형에 동일하게 적용됩니다. 예를 들어, 노트 경고도 동일한 서식과 줄바꿈을 요구합니다:

Content above.

/// note | Note title

Note text here.

///

Content below.

모든 지원되는 경고 유형은 경고로 사용할 수 있습니다.

탭으로 구분된 콘텐츠¶

탭으로 구분된 콘텐츠는 다음과 같이 서식이 지정되며, 콘텐츠 블록 시작 전과 종료 후에는 줄바꿈이 포함됩니다:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

중첩된 경고가 포함된 탭은 다음과 같이 서식이 지정되며, 콘텐츠 블록 앞뒤에 줄바꿈이 포함됩니다:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

접힌 콘텐츠¶

접힌 콘텐츠는 다음과 같이 서식화되며, 줄바꿈을 포함합니다:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

모든 지원되는 경고 유형은 접힌 콘텐츠와 함께 사용할 수 있지만, 반드시 details-admonitiontype로 선언해야 합니다. 따라서 "참고" 유형의 접힌 블록은 details-note (위 예시 참조), "경고" 유형의 접힌 블록은 details-warning 등이 됩니다.

진자 지침¶

문서에는 텍스트 내에서 Jinja 지시어를 사용하는 몇 가지 기능이 있습니다. Jinja 지시어 기능을 사용하는 모든 내용은 줄바꿈으로 감싸야 합니다. 예를 들어, BeeWare 튜토리얼에는 메인 페이지에 표시할 경고를 결정하기 위해 변수를 기반으로 한 Jinja 조건문이 포함되어 있습니다. 해당 내용은 다음과 같이 형식화됩니다:

Content above.



Content below.

기호나 텍스트를 대체하는 구문도 존재합니다. 이 구문은 쌍으로 된 중괄호로 감싸진 변수이며, 단독 행에 있을 경우 앞뒤로 줄바꿈을 포함해야 합니다.

Content above.

{{ variable }}

Content below.

이미지 서식 지정¶

이미지는 너비를 설정할 수 있으며, 왼쪽, 오른쪽, 중앙 정렬이 가능합니다(단, "중앙" 정렬에는 주의사항이 있습니다). 접근성 목적으로 이미지는 항상 의미 있는 대체 텍스트를 포함해야 합니다.

이미지의 너비를 300px로 설정하는 형식은 다음과 같습니다:

![Image alt text](../path/to/image.png){ width="300px" }

이미지를 왼쪽(또는 오른쪽)에 정렬하는 형식은 다음과 같습니다:

![Image alt text](../path/to/image.png){ align=left }

이미지에 캡션을 추가하려면 앞뒤에 줄바꿈이 필요하며, 다음과 같이 서식이 지정됩니다:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

align 속성으로는 이미지 중심 정렬이 불가능합니다. 해결 방법은 이미지 뒤에 빈 캡션을 추가하면 중앙 정렬됩니다. 각 섹션 사이와 앞뒤에 반드시 줄바꿈을 포함해야 합니다. 형식은 다음과 같습니다:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

특정 마크다운 서식을 지원하는 플러그인¶

다음 섹션에서는 특정 마크다운 서식이 필요한 플러그인을 활용하는 방법을 다룹니다.

스니펫을 사용하여 외부 콘텐츠 포함하기¶

로컬 파일이나 URL에서 외부 콘텐츠를 포함하는 방법에 대한 자세한 내용은 Snippets 확장 기능 문서을 참조하십시오. 문서에 실행이 필요한 Jinja 지시문이 포함되어 있지 않은 경우 Snippets를 사용해야 합니다(Jinja 실행은 Snippets 처리와 동시에 이루어지므로, 파일에 포함된 Jinja는 처리되지 않습니다). 파일을 특정 부분별로 분리하여 포함할 수 있는 구분자를 사용하려면 스니펫이 필요합니다. 예를 들어, 소스 문서가 서로 별도로 삽입될 섹션으로 나뉘어 있는 경우입니다.

중요 사항:

우리는 -8<-를 스니펫 식별자로 사용합니다. 문서에는 여러 옵션이 제시되어 있으나, 저희 스타일을 따르시기 바랍니다.
BeeWare Docs Tools 공유 콘텐츠에서 발견된 파일은 "로컬" 콘텐츠로 처리됩니다. 따라서 -8<- "docs-style-guide.md"와 같이 파일명만 사용하거나, 콘텐츠가 하위 디렉터리에 있는 경우 -8<- "style/docs-style-guide.md"와 같이 디렉터리와 파일명만 사용하게 됩니다.
GitHub의 파일에서 URL을 통해 외부 콘텐츠를 포함하는 경우, 반드시 원본 콘텐츠 URL을 사용해야 합니다. 그렇지 않으면 포함된 위치에 전체 웹 페이지가 렌더링됩니다.

BeeWare 문서 도구에서 공유된 콘텐츠를 매크로를 사용하여 포함하기¶

Macros MkDocs 플러그인을 사용하여 BeeWare Docs 도구의 공유 콘텐츠 디렉터리에서 콘텐츠를 포함할 수도 있습니다. 이 방법은 문서에 실행이 필요한 Jinja 지시어가 포함된 경우에만 사용해야 하며, 반드시 필요한 경우에만 사용하십시오. URL을 통한 외부 콘텐츠에는 작동하지 않습니다. Macros 변수 대체 메커니즘은 이 방법과 호환됩니다.

매크로를 사용하여 콘텐츠를 포함하는 옵션이 있습니다:

문서를 다른 수동 변경 없이 포함하려면 include Jinja 구문을 사용하십시오.
문서에 Jinja extends 구문을 포함시킨 경우, 특정 섹션을 재정의하거나 추가할 수 있도록 [Jinja (https://jinja.palletsprojects.com/en/stable/templates/#child-template) 구문]block을 사용하십시오.

`pyspelling`¶

우리는 pyspelling 맞춤법 검사기를 사용합니다. 이 검사기는 lint 검사 중에 실행됩니다.

pyspelling가 맞춤법 오류 단어를 표시할 경우, 대부분의 경우 문서 콘텐츠에서 수정해야 합니다.

pyspelling 사전에는 없지만 유효한 단어를 식별하는 드문 경우라면, 두 가지 선택지가 있습니다:

여러 번 재사용될 가능성이 있는 단어라면, 해당 단어를 spelling_wordlist 디렉토리 내의 docs 문서에 알파벳 순서로 추가해야 합니다.
다시 사용될 가능성이 낮은 단어라면 <nospell> / </nospell> 태그로 감싸면, pyspelling가 인라인에서 이를 무시합니다.