# 문서 작성 가이드라인 ```{contents} --- local: depth: 1 --- ``` (writing_style_guide)= ## 글쓰기 스타일 가이드 Wagtail 문서 작성 시 어조와 언어의 일관성을 보장하기 위해 [Google 개발자 문서 스타일 가이드](https://developers.google.com/style)를 따릅니다. ## 서식 권장사항 Wagtail의 문서는 [Markdown (MyST 포함)](inv:myst#syntax/core)과 [reStructuredText](inv:sphinx#rst-primer)를 혼용합니다. 특별한 이유가 없다면 먼저 Markdown으로 문서를 작성하고, 더 고급 서식이 필요할 때만 reStructuredText를 사용하는 것을 권장합니다. Python 코드의 Docstring은 아직 Markdown을 지원하지 않으므로 반드시 reStructuredText로 작성해야 합니다. Wagtail 문서 작성 시 권장하는 서식은 다음과 같습니다. ### 문단 모든 것은 여기서 시작됩니다. 문장은 짧게, 길이는 다양하게 유지하세요. 빈 줄로 텍스트를 구분하여 새 문단을 만듭니다. ### 라틴어 구문 및 약어 라틴어 구문(\ `ergo`\ 또는\ `de facto`\ 등)과 약어(\ `i.e.`\ 또는\ `e.g.`\ 등)의 사용을 피하고, 대신 일반적인 영어 구문을 사용하세요. 또는 독자에게 개념이나 아이디어를 더 간단하게 전달할 방법을 찾으세요. 예외적으로\ `etc.`\ 는 공간이 제한될 때 사용할 수 있습니다. 예시: | 이것을 사용하지 마세요 | 대신 이것을 사용하세요 | | -------------- | -------------------- | | e.g. | for example, such as (예를 들어) | | i.e. | that is (즉) | | viz. | namely (다시 말해) | | ergo | therefore (그러므로) | ### 제목 레벨 제목 레벨을 사용하여 섹션을 만들고, 사용자가 특정 섹션으로 바로 링크할 수 있도록 하세요. 문서는\ `# h1`\ 으로 시작하고, 레벨을 건너뛰지 않고\ `## h2`\ 및 하위 섹션으로 진행하세요. ```md # 제목 레벨 1 ## 제목 레벨 2 ### 제목 레벨 3 ``` ### 목록 순서 없는 목록에는 글머리 기호를, 순서가 있는 목록에는 숫자를 사용하세요. 글머리 기호는 대시(\ `-\`\ )를 선호합니다. 4칸 들여쓰기로 중첩할 수 있습니다. ```md - 글머리 기호 1 - 글머리 기호 2 - 중첩된 글머리 기호 2 - 글머리 기호 3 1. 번호 목록 1 2. 번호 목록 2 3. 번호 목록 3 ```
렌더링 결과 - 글머리 기호 1 - 글머리 기호 2 - 중첩된 글머리 기호 2 - 글머리 기호 3 1. 번호 목록 1 2. 번호 목록 2 3. 번호 목록 3
### 인라인 스타일 **굵게** 와 _기울임꼴_ 은 드물게 사용하고, 관련이 있을 때는 인라인\ `code`\ 를 사용하세요. ```md **굵게** 와 _기울임꼴_ 은 드물게 사용하고, 관련이 있을 때는 인라인\ `code`\ 를 사용하세요. ``` reStructuredText에서는 기울임꼴을\ `*`\ 로, 인라인 코드는\ ` ``code`` `\ 처럼 이중 백틱으로 작성해야 한다는 점을 기억하세요. ```rst **굵게** 와 *기울임꼴* 은 드물게 사용하고, 관련이 있을 때는 인라인\ ``code``\ 를 사용하세요. ``` ### 코드 블록 구문 강조를 위해 올바른 언어 코드를 포함하고, 코딩 가이드라인에 따라 코드 서식을 지정해야 합니다. 자주 사용되는 언어: `python`\ , \`css\`\ , \`html\`\ , \`html+django\`\ , \`javascript\`\ , \`sh\`\ . ````md ```python INSTALLED_APPS = [ ... "wagtail", ... ] ``` ````
렌더링 결과 ```python INSTALLED_APPS = [ ... "wagtail", ... ] ```
#### 콘솔 (터미널) 코드 블록 사용 시 ```{note} `$`\ 나\ `>`\ 프롬프트는 필요하지 않습니다. 이는 줄을 복사하여 붙여넣기 어렵게 만들고 모든 코드 스니펫에 일관되게 추가하기 어려울 수 있습니다. ``` `sh`\ 는 MyST 파서에서 주석 및 코드 구문 강조를 더 잘 지원하고 GitHub 및 VSCode와 더 호환되므로\ `sh`\ 를 사용하세요. ````md ```sh # 주석 some command ``` ````
렌더링 결과 ```sh # 주석 some command ```
`doscon`\ (DOS 콘솔)은 bash에 해당하는 명령어와 함께 Windows 명령어를 명시적으로 언급할 때만 사용하세요. ````md ```doscon # 주석 some command ``` ````
렌더링 결과 ```doscon # 주석 some command ```
#### 세 개의 백틱을 포함하는 코드 블록 세 개 이상의 백틱을 사용하여 코드 블록을 만들 수 있습니다. 코드 블록에 세 개의 백틱을 포함해야 하는 경우, 다른 개수의 백틱으로 코드 블록을 감쌀 수 있습니다. 이는 위 예시와 같이 Markdown 코드 블록을 시연해야 할 때 유용합니다. `````md ````md ```python print("Hello, world!") ``` ```` `````
렌더링 결과 ````md ```python print("Hello, world!") ``` ````
### 링크 링크는 문서의 기본입니다. 내부 링크를 사용하여 콘텐츠를 다른 문서에 연결하고, 필요에 따라 외부 링크를 사용하세요. 독자가 어디로 이동할지 알 수 있도록 링크에 관련성 있는 텍스트를 선택하세요. 외부 링크가 독자에게 중요한 맥락을 숨기게 두지 마세요. 대신, 페이지에 핵심 정보를 제공하고 추가적인 맥락을 위해 링크를 사용하세요. ```md [외부 링크](https://wwww.example.com). [다른 문서로의 내부 링크](/reference/contrib/legacy_richtext). 페이지로 자동 생성된 링크 레이블 [](/getting_started/tutorial). [대상으로의 링크](register_reports_menu_item). 링크 텍스트로 [여기를 클릭하세요](https://www.example.com)를 사용하지 말고, 더 설명적인 레이블을 사용하세요. [이것이 왜 중요한지](https://www.example.com)와 같이 중요한 맥락을 링크에 의존하지 마세요. ```
렌더링 결과 [외부 링크](https://wwww.example.com). [다른 문서로의 내부 링크](/reference/contrib/legacy_richtext). 페이지로 자동 생성된 링크 레이블 [](/getting_started/tutorial). [대상으로의 링크](register_reports_menu_item). 링크 텍스트로 [여기를 클릭하세요](https://www.example.com)를 사용하지 말고, 더 설명적인 레이블을 사용하세요. [이것이 왜 중요한지](https://www.example.com)와 같이 중요한 맥락을 링크에 의존하지 마세요.
#### 앵커 링크 앵커 링크는 페이지의 특정 대상을 가리킵니다. 페이지에 대상이 생성되어 있어야 합니다. 각 대상은 고유한 이름을 가져야 하며\ `lower_snake_case`\ 형식을 사용해야 합니다. 대상은 다음과 같이 추가할 수 있습니다: ```md (my_awesome_section)= ##### 멋진 섹션 제목 ... ``` 대상은 다음과 같이 Markdown 링크 구문을 사용하여 선택적 레이블과 함께 링크할 수 있습니다: ```md - 자동 생성 레이블 (권장) [](my_awesome_section) - [섹션 레이블](my_awesome_section) ``` 렌더링 결과: (my_awesome_section)= ##### 멋진 섹션 제목 ... - 자동 생성 레이블 (권장) [](my_awesome_section) - [섹션 레이블](my_awesome_section) MyST-Parser 문서의 [](inv:myst#syntax/cross-referencing) 섹션에서 다른 연결 및 참조 생성 방법에 대해 더 자세히 읽을 수 있습니다. #### Intersphinx 링크 (외부 문서) 외부 문서(특히 Django)에 대한 링크가 많기 때문에, intersphinx 참조를 통한 통합을 추가했습니다. 이는\ `docs/conf.py`\ 파일의 [](inv:sphinx:std:confval#intersphinx_mapping)를 통해 구성됩니다. 이를 통해 프로젝트 문서의 특정 섹션에 연결하고 대상이 더 이상 사용할 수 없을 때 경고를 받을 수 있습니다. Markdown 예시: ```md [Django의 양식 위젯](inv:django#ref/forms/widgets)에서 위젯을 선택할 수 있습니다. ``` reStructuredText 예시: ```rst :doc:`Django 양식 위젯 ` 에서 위젯을 선택할 수 있습니다. ``` Markdown에서 Sphinx 링크 형식은\ `inv:key:domain:type#name`\ 입니다. \`key\`\ , \`domain\`\ , \`type\`\ 은 선택 사항이지만, 동일한\ `name`\ 을 가진 대상이 여러 개 있을 때 모호성을 피하기 위해 권장됩니다. `name`\ 에 공백이 포함된 경우, 전체 링크를 꺾쇠괄호\ `<>`\ 로 감싸야 합니다. ```md Django 문서의 []()를 참조하세요. ```
렌더링 결과 Django 문서의 []()를 참조하세요.
##### 올바른 intersphinx 대상 찾기 연결하려는 특정 앵커에 대한 intersphinx 대상이 명확하지 않을 수 있습니다. MyST-Parser의\ `myst-inv`\ 명령줄 도구를 사용하고 출력을 JSON 또는 YAML 파일로 저장하여 사용 가능한 대상의 시각적 표현을 얻을 수 있습니다. ```sh myst-inv https://docs.djangoproject.com/en/stable/_objects/ --format=json > django-inv.json ``` `myst-inv`\ 의 출력을 사용하여\ `objects`\ 키 아래의 트리 구조를 따라 링크 대상을 구성할 수 있습니다. VSCode와 같은 일부 텍스트 편집기는 파일을 탐색할 때 대상까지의 경로(breadcrumbs)를 보여줄 수 있습니다. [sphobjinv](https://github.com/bskinn/sphobjinv) 및 Sphinx에 내장된\ `sphinx.ext.intersphinx`\ 확장과 같이 Sphinx 인벤토리를 탐색하는 데 도움이 되는 다른 도구도 사용할 수 있습니다. ```sh sphobjinv suggest "https://docs.djangoproject.com/en/stable/_objects/" 'template fragment caching' -su python -m sphinx.ext.intersphinx https://docs.djangoproject.com/en/stable/_objects/ ``` 경우에 따라 문서에서 더 구체적인 대상을 사용할 수 있습니다. 그러나 이를 찾으려면 페이지의 소스 코드를 검사해야 할 수 있습니다. 예를 들어, Django 문서의 위 섹션은\ `templatetag`\ 유형과\ `cache`\ 이름을 통해서도 연결할 수 있습니다. ```md Django 문서의 [](inv:django:std:templatetag#cache) 태그를 참조하세요. ```
렌더링 결과 Django 문서의 [](inv:django:std:templatetag#cache) 태그를 참조하세요.
링크가 동일한 섹션으로 이동하더라도 URL 해시와 기본 텍스트는 다릅니다. 사용자 정의 텍스트를 사용하면 독자에게 차이가 없을 수 있지만, 의미적으로는 다릅니다. 캐싱 수행 방법에 대한 가이드와 같이 일반적인 문서의 맥락에서 연결할 때는 첫 번째 접근 방식(`label` 유형 사용)을 사용하세요.\ `{% cache %}`\ 템플릿 태그의 사용과 같이 코드 작성 맥락에서 연결할 때는 두 번째 접근 방식(`templatetag` 유형 사용)을 사용하세요. Docstring을 작성할 때는 일반적으로 두 번째 접근 방식이 선호됩니다. #### 절대 링크 때로는 외부 문서의 섹션에 Sphinx 대상이 전혀 연결되어 있지 않은 경우가 있습니다. 이러한 섹션에 연결하기 전에 해당 섹션 바로 앞의 가장 가까운 대상에 연결하는 것을 고려하세요. 링크를 클릭했을 때 의도한 섹션이 즉시 보일 만큼 가까운 대상이 있다면 그것을 사용하세요. 그렇지 않으면 전체 URL로 작성할 수 있습니다. 특정 버전이 아닌\ `stable`\ URL을 사용해야 함을 기억하세요. intersphinx 링크 대신 전체 URL을 사용하는 일반적인 예는 Django의 릴리스 노트 섹션에 연결할 때입니다. ```md `DeleteView`\ 는 [Django 4.0의\ `DeleteView`\ 구현](https://docs.djangoproject.com/en/stable/releases/4.0/#deleteview-changes)에 맞춰 업데이트되었습니다. ```
렌더링 결과 `DeleteView`\ 는 [Django 4.0의\ `DeleteView`\ 구현](https://docs.djangoproject.com/en/stable/releases/4.0/#deleteview-changes)에 맞춰 업데이트되었습니다.
intersphinx 매핑이 없는 웹사이트로의 외부 링크의 경우, 항상\ `https://`\ 스킴을 사용하세요. Sphinx 객체 인벤토리가 있더라도 외부 문서에 대한 일회성 링크에는 절대 링크가 선호됩니다. 동일한 프로젝트에 대한 링크가 세 개 이상 되면, 가능하다면 intersphinx 매핑을 추가하는 것을 고려하세요. #### 코드 참조 코드 참조에 연결할 때 Sphinx의 [참조 역할(reference roles)](inv:sphinx#usage/restructuredtext/roles)을 사용할 수 있습니다. Markdown 예시: ```md {class}`~django.db.models.JSONField` 클래스는 {mod}`django.db.models.fields.json` 모듈에 있지만, {mod}`models ` 모듈에서 직접 가져올 수 있습니다. 자세한 정보는 {ref}`querying-jsonfield` 를 참조하세요. ``` reStructuredText 예시: ```rst :class:`~django.db.models.JSONField` 클래스는 :mod:`django.db.models.fields.json` 모듈에 있지만, :mod:`models ` 모듈에서 직접 가져올 수 있습니다. 자세한 정보는 :ref:`querying-jsonfield` 를 참조하세요. ```
렌더링 결과 {class}`~django.db.models.JSONField` 클래스는 {mod}`django.db.models.fields.json` 모듈에 있지만, {mod}`models ` 모듈에서 직접 가져올 수 있습니다. 자세한 정보는 {ref}`querying-jsonfield` 를 참조하세요.
점으로 구분된 경로 앞에\ `~`\ 를 추가하면 링크 텍스트가 마지막 부분(객체 이름)으로 줄어듭니다. 이는 전체 경로가 이미 텍스트에 언급된 경우 유용할 수 있습니다. 또한 [`module`](inv:sphinx:rst:directive#py:module) 또는 [`currentmodule`](inv:sphinx:rst:directive#py:currentmodule) 지시문을 사용하여 문서의 현재 범위를 설정하여 모든 객체에 대한 전체 경로를 작성하는 것을 피할 수 있습니다. ````md ```{currentmodule} wagtail.admin.viewsets.model ``` {class}`ModelViewSet` 클래스는 {class}`~wagtail.admin.viewsets.base.ViewSet` 클래스를 확장합니다. ````
렌더링 결과 ```{currentmodule} wagtail.admin.viewsets.model ``` The {class}`ModelViewSet` 클래스는 {class}`~wagtail.admin.viewsets.base.ViewSet` 클래스를 확장합니다.
```{currentmodule} None ``` 참조 역할은 자체 렌더링 방식을 정의할 수도 있습니다. 위 예시에서 [`class`](inv:sphinx:rst:role#py:class) 및 [`mod`](inv:sphinx:rst:role#py:mod) 역할은 링크가 있는 인라인 코드로 렌더링되지만, [`ref`](inv:sphinx:rst:role#ref) 역할은 일반 링크로 렌더링됩니다. 이러한 기능은 참조 유형의 문서와 Docstring을 작성할 때 참조 역할을 특히 유용하게 만듭니다. 참조 역할을 사용하는 것 외에도 링크 구문을 사용할 수 있습니다. 참조 역할과 달리 링크 구문은 객체에 대한 전체 경로가 필요하며 링크 레이블을 사용자 정의할 수 있습니다. 이는 예를 들어 인라인 코드와 일반 텍스트를 링크 레이블로 혼합하는 등 참조 역할의 기본 렌더링을 피하고 싶을 때 유용할 수 있습니다. ```md [`JSONField` 모델 필드](django.db.models.JSONField)를 쿼리하는 방법에 대한 자세한 내용은 [`JSONField` 쿼리 관련 섹션](inv:django#querying-jsonfield)을 참조하세요. ```
렌더링 결과 [`JSONField` 모델 필드](django.db.models.JSONField)를 쿼리하는 방법에 대한 자세한 내용은 [`JSONField` 쿼리 관련 섹션](inv:django#querying-jsonfield)을 참조하세요.
### 노트 및 경고 강조 상자 필요할 때 독자의 주의를 끌기 위해 노트와 경고를 드물게 사용하세요. 이는 추가적인 맥락을 제공하거나 잠재적인 문제에 대해 경고하는 데 사용할 수 있습니다. ```{note} 노트는 보충 정보를 제공할 수 있습니다. ``` ```{warning} 경고는 무서울 수 있습니다. ```
렌더링 결과 ```{note} 노트는 보충 정보를 제공할 수 있습니다. ``` ```{warning} 경고는 무서울 수 있습니다. ```
이러한 강조 상자는 제목을 지원하지 않으므로, 제목을 포함하지 않도록 주의하세요. 제목은 강조 상자의 본문으로 이동됩니다. ```{note} 여기의 제목은 제대로 작동하지 않습니다 노트는 보충 정보를 제공할 수 있습니다. ``` ### 이미지 문서가 발전함에 따라 이미지를 최신 상태로 유지하기는 어렵지만, 그럼에도 불구하고 가치가 있을 수 있습니다. 이미지를 추가할 때의 가이드라인은 다음과 같습니다. - 장식용이 아닌 모든 이미지에는 의미 있는 [alt 텍스트](https://axesslab.com/alt-texts/)가 있어야 합니다. - 이미지는 있는 그대로 제공됩니다 – 올바른 형식을 선택하고 모든 이미지를 무손실 압축하세요. - 이미지 파일에는 절대 경로를 사용하여 이식성을 높이세요. ```md ![TableBlock 컴포넌트가 StreamField에 있으며, 행 헤더, 열 헤더, 캡션 필드가 있고, 그 다음 편집 가능한 테이블이 있습니다.](/_static/images/screen40_table_block.png) ```
렌더링 결과 ![TableBlock 컴포넌트가 StreamField에 있으며, 행 헤더, 열 헤더, 캡션 필드가 있고, 그 다음 편집 가능한 테이블이 있습니다.](/_static/images/screen40_table_block.png)
### Docstrings 및 API 참조 (autodoc) Sphinx는 [autodoc](inv:sphinx#ext-autodoc) 기능을 통해 Python Docstring으로 문서를 작성하고 이를 프로젝트의 문서 페이지에 통합하는 것을 지원합니다. 이는 Wagtail의 API를 문서화하는 데 매우 강력한 기능이므로 사용을 적극 권장합니다. 모듈, 클래스, 함수는 Docstring으로 문서화할 수 있습니다. 클래스 및 인스턴스 속성은 Docstring(세 개의 따옴표\ `"""`\ ) 또는 문서 주석(해시-콜론\ `#:`)으로 문서화할 수 있습니다. Docstring은 코드 편집기와의 통합이 더 좋으므로 선호됩니다. Python 코드의 Docstring은 reStructuredText 구문으로 작성해야 합니다. ```py SLUG_REGEX = r'^[-a-zA-Z0-9_]+$' """모듈 수준 변수 ``SLUG_REGEX`` 에 대한 Docstring.""" class Foo: """클래스 ``Foo`` 에 대한 Docstring.""" bar = 1 """클래스 속성 ``Foo.bar`` 에 대한 Docstring.""" #: 클래스 속성 ``Foo.baz`` 에 대한 문서 주석. #: 여러 줄일 수 있으며, 각 줄은 ``#:`` 로 시작해야 합니다. #: 속성 앞에 작성된다는 점에 유의하세요. #: Sphinx가 이를 지원하지만 권장되지는 않습니다. baz = 2 def __init__(self): self.spam = 4 """인스턴스 속성 ``spam`` 에 대한 Docstring.""" ``` autodoc 확장은 [`autoclass`](inv:sphinx#autoclass), [`autofunction`](inv:sphinx#autofunction), [`automodule`](inv:sphinx#automodule)과 같이 Python 코드를 문서화하기 위한 많은 지시문과 출력을 사용자 정의하기 위한 다양한 옵션을 제공합니다. Markdown 파일에서 이러한 지시문은\ `eval-rst`\ 지시문으로 감싸야 합니다. Docstring과 마찬가지로\ `eval-rst`\ 블록 안의 모든 것은 reStructuredText 구문으로 작성해야 합니다. 자동 문서화와 비자동 문서화를 혼합할 수 있습니다. 예를 들어, `automodule` 대신 [`module`](inv:sphinx#py:module)을 사용하고 모듈의 문서를\ `eval-rst`\ 블록에 작성하면서도, 클래스와 함수에 대해서는 여전히\ `autoclass`\ 와\ `autofunction`\ 을 사용할 수 있습니다. 자동 문서화는 코드와 문서 간의 불일치 위험을 줄이고 코드 편집기와의 더 나은 통합을 제공하므로 권장됩니다. ```{eval-rst} .. module:: wagtail.coreutils Wagtail의 핵심 유틸리티입니다. .. autofunction:: cautious_slugify :no-index: ```
렌더링 결과 ```{eval-rst} .. module:: wagtail.coreutils :no-index: Wagtail의 핵심 유틸리티입니다. .. autofunction:: cautious_slugify :no-index: ```
사용 가능한 지시문과 옵션에 대한 자세한 내용은 Sphinx 문서의 [](inv:sphinx#autodoc-directives)와 [](inv:sphinx#usage/domains/python)을 참조하세요. ### 테이블 필요할 때만 [GitHub Flavored Markdown 테이블 구문](https://github.github.com/gfm/#tables-extension-)을 사용하여 테이블을 사용하세요. ```md | 브라우저 | 기기/OS | | ------------- | --------- | | 기본 브라우저 | Android | | IE | 데스크톱 | | Safari | Windows | ```
렌더링 결과 | 브라우저 | 기기/OS | | --- | --- | | 기본 브라우저 | Android | | IE | 데스크톱 | | Safari | Windows |
### 목차 [`toctree` 및 `contents` 지시문](inv:myst#organising-content)을 사용하여 목차를 렌더링할 수 있습니다. ```{toctree} --- maxdepth: 2 titlesonly: --- getting_started/index topics/index ``` ```{contents} --- local: depth: 1 --- ``` ### 버전 추가, 변경, 폐지 알림 Sphinx는 새롭거나 업데이트된 기능에 대한 정보를 일관된 방식으로 제공하기 위해 릴리스 메타데이터 지시문을 제공합니다. ```{versionadded} 2.15 `WAGTAIL_NEW_SETTING` 설정이 추가되었습니다. ``` ```{versionchanged} 2.15 `WAGTAIL_OLD_SETTING` 설정은 폐지되었습니다. ```
렌더링 결과 ```{versionadded} 2.15 `WAGTAIL_NEW_SETTING` 설정이 추가되었습니다. ``` ```{versionchanged} 2.15 `WAGTAIL_OLD_SETTING` 설정은 폐지되었습니다. ```
이러한 지시문은 일반적으로 추가된 후 두 릴리스가 지나면 제거되므로, "The\ `WAGTAILIMAGES_CACHE_DURATION`\ setting was added"와 같이 단기적인 정보에만 사용해야 합니다. 기능에 대한 자세한 문서는 지시문 외부의 본문에 있어야 합니다. ### 점진적 공개 HTML `
` 요소를 사용하여 문서에 보충 정보를 추가할 수 있습니다. 이는 HTML 구문에 의존하므로 일관성 있게 작성하기 어려울 수 있으므로 이러한 유형의 서식은 최소한으로 유지하세요. ```html
보충 정보 이 내용은 콘텐츠를 펼쳤을 때 보입니다.
``` 예시:
보충 정보 이 내용은 콘텐츠를 펼쳤을 때 보입니다.
## 피해야 할 서식 문서에서 기술적으로 지원되지만, 명확한 필요성이 없는 한 피하는 것이 좋은 몇 가지 서식이 있습니다. ### 강조 상자 우리는\ `{note}`\ 와\ `{warning}`\ 강조 상자만 사용합니다. `{admonition}`, `{important}`, `{topic}`, `{tip}` 은 피하세요. 이러한 것들을 발견하면\ `{note}`\ 로 교체해주세요. ### 용어집 Sphinx 용어집(`.. glossary::`)은 정의 목록을 생성합니다. 대신 일반 글머리 기호나 번호 목록, 제목이 있는 섹션 또는 테이블을 사용하세요. ### 주석 커밋된 문서의 소스에는 주석을 피하세요. ### 그림 reStructuredText 그림(`.. figure::`)은 일반 이미지에 비해 아주 미미한 개선만을 제공합니다. 그림에 캡션이 있다면 이미지 아래에 기울임꼴 문단으로 추가하세요. ### 기타 reStructuredText 구문 및 Sphinx 지시문 우리는 일반적으로 reStructuredText보다 Markdown을 선호하여, 새로운 기여자들이 Wagtail 문서에 기여하는 것을 최대한 간단하게 만들고 싶습니다. 문서의 서식이 reStructuredText 구문에 크게 의존하지 않는 한 항상 Markdown을 선호하세요. 특정 Sphinx 지시문을 사용하고 싶다면, 핵심 기여자들과 상의하여 그 사용이 정당한지 확인하고 예상되는 사용법을 이 페이지에 문서화하세요. ### reStructuredText 안의 Markdown 반대로, reStructuredText가 필요한 곳에 Markdown 구문을 사용하지 마세요. 흔한 실수는 Python 코드 Docstring이나\ `eval-rst`\ 지시문 안에 Markdown 스타일의 인라인\ `code`\ (단일 백틱)를 작성하는 것입니다. 이는 지원되지 않으며 올바르게 렌더링되지 않습니다. ### 임의의 HTML 우리의 문서 도구가 임의의 HTML 임베딩을 일부 지원하지만, 이는 권장되지 않습니다. 필요성이 있고 서식이 업데이트될 가능성이 거의 없는 경우에만 사용하세요. (documentation_code_example_considerations)= ## 코드 예제 고려사항 코드 예제, 특히 JavaScript나 임베디드 HTML을 포함할 때, 보안, 접근성 및 예제를 더 쉽게 이해할 수 있도록 하는 모범 사례를 따르는 것이 중요합니다. 이는 엄격한 규칙이라기보다는 예제 코드를 작성할 때 고려해야 할 사항입니다. ### 참조 예제 파일 이름 코드 스니펫의 시작 부분에 예제 파일 이름을 참조하는 것이 도움이 될 수 있습니다. 예를 들어, `# wagtail_hooks.py` 또는 `// js/my-custom.js` 와 같습니다. ### CSP (콘텐츠 보안 정책) 준수 외부 소스나 사용자 정의 스크립트에서 JavaScript를 추가할 때, 교차 사이트 스크립팅(XSS)과 같은 보안 취약점을 방지하기 위해 CSP 준수를 확인하세요. 가능한 한\ `mark_safe`\ 사용을 피하고, `format_html`\ 을 사용하며, 인라인\ `