문서 작성 가이드라인¶

문단¶

모든 것은 여기서 시작됩니다. 문장은 짧게, 길이는 다양하게 유지하세요.

빈 줄로 텍스트를 구분하여 새 문단을 만듭니다.

라틴어 구문 및 약어¶

라틴어 구문(\ ergo\ 또는\ de facto\ 등)과 약어(\ i.e.\ 또는\ e.g.\ 등)의 사용을 피하고, 대신 일반적인 영어 구문을 사용하세요. 또는 독자에게 개념이나 아이디어를 더 간단하게 전달할 방법을 찾으세요. 예외적으로\ etc.\ 는 공간이 제한될 때 사용할 수 있습니다.

예시:

제목 레벨¶

제목 레벨을 사용하여 섹션을 만들고, 사용자가 특정 섹션으로 바로 링크할 수 있도록 하세요. 문서는\ # h1\ 으로 시작하고, 레벨을 건너뛰지 않고\ ## h2\ 및 하위 섹션으로 진행하세요.

# 제목 레벨 1

## 제목 레벨 2

### 제목 레벨 3

목록¶

순서 없는 목록에는 글머리 기호를, 순서가 있는 목록에는 숫자를 사용하세요. 글머리 기호는 대시(\ -\\ )를 선호합니다. 4칸 들여쓰기로 중첩할 수 있습니다.

-   글머리 기호 1
-   글머리 기호 2
    -   중첩된 글머리 기호 2
-   글머리 기호 3

1. 번호 목록 1
2. 번호 목록 2
3. 번호 목록 3

인라인 스타일¶

굵게 와 기울임꼴 은 드물게 사용하고, 관련이 있을 때는 인라인\ code\ 를 사용하세요.

**굵게** 와 _기울임꼴_ 은 드물게 사용하고, 관련이 있을 때는 인라인\ `code`\ 를 사용하세요.

reStructuredText에서는 기울임꼴을\ *\ 로, 인라인 코드는\ ``code``\ 처럼 이중 백틱으로 작성해야 한다는 점을 기억하세요.

**굵게** 와 *기울임꼴* 은 드물게 사용하고, 관련이 있을 때는 인라인\ ``code``\ 를 사용하세요.

코드 블록¶

구문 강조를 위해 올바른 언어 코드를 포함하고, 코딩 가이드라인에 따라 코드 서식을 지정해야 합니다. 자주 사용되는 언어: python\ , `css`\ , `html`\ , `html+django`\ , `javascript`\ , `sh`\ .

```python
INSTALLED_APPS = [
    ...
    "wagtail",
    ...
]
```

INSTALLED_APPS = [
    ...
    "wagtail",
    ...
]

```sh
# 주석
some command
```

# 주석
some command

```doscon
# 주석
some command
```

# 주석
some command

````md
```python
print("Hello, world!")
```
````

```python
print("Hello, world!")
```

링크¶

링크는 문서의 기본입니다. 내부 링크를 사용하여 콘텐츠를 다른 문서에 연결하고, 필요에 따라 외부 링크를 사용하세요. 독자가 어디로 이동할지 알 수 있도록 링크에 관련성 있는 텍스트를 선택하세요.

외부 링크가 독자에게 중요한 맥락을 숨기게 두지 마세요. 대신, 페이지에 핵심 정보를 제공하고 추가적인 맥락을 위해 링크를 사용하세요.

[외부 링크](https://wwww.example.com).
[다른 문서로의 내부 링크](/reference/contrib/legacy_richtext).
페이지로 자동 생성된 링크 레이블 [](/getting_started/tutorial).
[대상으로의 링크](register_reports_menu_item).
링크 텍스트로 [여기를 클릭하세요](https://www.example.com)를 사용하지 말고, 더 설명적인 레이블을 사용하세요.
[이것이 왜 중요한지](https://www.example.com)와 같이 중요한 맥락을 링크에 의존하지 마세요.

(my_awesome_section)=

##### 멋진 섹션 제목

...

-   자동 생성 레이블 (권장) [](my_awesome_section)
-   [섹션 레이블](my_awesome_section)

[Django의 양식 위젯](inv:django#ref/forms/widgets)에서 위젯을 선택할 수 있습니다.

:doc:`Django 양식 위젯 <django:ref/forms/widgets>` 에서 위젯을 선택할 수 있습니다.

Django 문서의 [](<inv:django:std:label#topics/cache:template fragment caching>)를 참조하세요.

myst-inv https://docs.djangoproject.com/en/stable/_objects/ --format=json > django-inv.json

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 문서의 [](inv:django:std:templatetag#cache) 태그를 참조하세요.

`DeleteView`\ 는 [Django 4.0의\ `DeleteView`\ 구현](https://docs.djangoproject.com/en/stable/releases/4.0/#deleteview-changes)에 맞춰 업데이트되었습니다.

{class}`~django.db.models.JSONField` 클래스는 {mod}`django.db.models.fields.json` 모듈에 있지만,
{mod}`models <django.db.models>` 모듈에서 직접 가져올 수 있습니다.
자세한 정보는 {ref}`querying-jsonfield` 를 참조하세요.

:class:`~django.db.models.JSONField` 클래스는 :mod:`django.db.models.fields.json` 모듈에 있지만,
:mod:`models <django.db.models>` 모듈에서 직접 가져올 수 있습니다.
자세한 정보는 :ref:`querying-jsonfield` 를 참조하세요.

```{currentmodule} wagtail.admin.viewsets.model

```

{class}`ModelViewSet` 클래스는 {class}`~wagtail.admin.viewsets.base.ViewSet` 클래스를 확장합니다.

[`JSONField` 모델 필드](django.db.models.JSONField)를 쿼리하는 방법에 대한 자세한 내용은
[`JSONField` 쿼리 관련 섹션](inv:django#querying-jsonfield)을 참조하세요.

노트 및 경고 강조 상자¶

필요할 때 독자의 주의를 끌기 위해 노트와 경고를 드물게 사용하세요. 이는 추가적인 맥락을 제공하거나 잠재적인 문제에 대해 경고하는 데 사용할 수 있습니다.

```{note}
노트는 보충 정보를 제공할 수 있습니다.
```

```{warning}
경고는 무서울 수 있습니다.
```

이러한 강조 상자는 제목을 지원하지 않으므로, 제목을 포함하지 않도록 주의하세요. 제목은 강조 상자의 본문으로 이동됩니다.

```{note} 여기의 제목은 제대로 작동하지 않습니다
노트는 보충 정보를 제공할 수 있습니다.
```

이미지¶

문서가 발전함에 따라 이미지를 최신 상태로 유지하기는 어렵지만, 그럼에도 불구하고 가치가 있을 수 있습니다. 이미지를 추가할 때의 가이드라인은 다음과 같습니다.

• 장식용이 아닌 모든 이미지에는 의미 있는 alt 텍스트가 있어야 합니다.

• 이미지는 있는 그대로 제공됩니다 – 올바른 형식을 선택하고 모든 이미지를 무손실 압축하세요.

• 이미지 파일에는 절대 경로를 사용하여 이식성을 높이세요.

![TableBlock 컴포넌트가 StreamField에 있으며, 행 헤더, 열 헤더, 캡션 필드가 있고, 그 다음 편집 가능한 테이블이 있습니다.](/_static/images/screen40_table_block.png)

Docstrings 및 API 참조 (autodoc)¶

Sphinx는 autodoc 기능을 통해 Python Docstring으로 문서를 작성하고 이를 프로젝트의 문서 페이지에 통합하는 것을 지원합니다. 이는 Wagtail의 API를 문서화하는 데 매우 강력한 기능이므로 사용을 적극 권장합니다.

모듈, 클래스, 함수는 Docstring으로 문서화할 수 있습니다. 클래스 및 인스턴스 속성은 Docstring(세 개의 따옴표\ """\ ) 또는 문서 주석(해시-콜론\ #:)으로 문서화할 수 있습니다. Docstring은 코드 편집기와의 통합이 더 좋으므로 선호됩니다. Python 코드의 Docstring은 reStructuredText 구문으로 작성해야 합니다.

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, autofunction, automodule과 같이 Python 코드를 문서화하기 위한 많은 지시문과 출력을 사용자 정의하기 위한 다양한 옵션을 제공합니다. Markdown 파일에서 이러한 지시문은\ eval-rst\ 지시문으로 감싸야 합니다. Docstring과 마찬가지로\ eval-rst\ 블록 안의 모든 것은 reStructuredText 구문으로 작성해야 합니다.

자동 문서화와 비자동 문서화를 혼합할 수 있습니다. 예를 들어, automodule 대신 module을 사용하고 모듈의 문서를\ eval-rst\ 블록에 작성하면서도, 클래스와 함수에 대해서는 여전히\ autoclass\ 와\ autofunction\ 을 사용할 수 있습니다. 자동 문서화는 코드와 문서 간의 불일치 위험을 줄이고 코드 편집기와의 더 나은 통합을 제공하므로 권장됩니다.

```{eval-rst}
.. module:: wagtail.coreutils

    Wagtail의 핵심 유틸리티입니다.

    .. autofunction:: cautious_slugify
        :no-index:
```

사용 가능한 지시문과 옵션에 대한 자세한 내용은 Sphinx 문서의 Directives와 The Python Domain을 참조하세요.

테이블¶

필요할 때만 GitHub Flavored Markdown 테이블 구문을 사용하여 테이블을 사용하세요.

| 브라우저 | 기기/OS |
| ------------- | --------- |
| 기본 브라우저 | Android |
| IE | 데스크톱 |
| Safari | Windows |

목차¶

toctree 및 contents 지시문을 사용하여 목차를 렌더링할 수 있습니다.

```{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` 설정은 폐지되었습니다.
```

이러한 지시문은 일반적으로 추가된 후 두 릴리스가 지나면 제거되므로, “The\ WAGTAILIMAGES_CACHE_DURATION\ setting was added”와 같이 단기적인 정보에만 사용해야 합니다. 기능에 대한 자세한 문서는 지시문 외부의 본문에 있어야 합니다.

점진적 공개¶

HTML <details> 요소를 사용하여 문서에 보충 정보를 추가할 수 있습니다. 이는 HTML 구문에 의존하므로 일관성 있게 작성하기 어려울 수 있으므로 이러한 유형의 서식은 최소한으로 유지하세요.

<details>
    <summary>보충 정보</summary>

    이 내용은 콘텐츠를 펼쳤을 때 보입니다.
</details>

예시:

강조 상자¶

우리는\ {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 임베딩을 일부 지원하지만, 이는 권장되지 않습니다. 필요성이 있고 서식이 업데이트될 가능성이 거의 없는 경우에만 사용하세요.

참조 예제 파일 이름¶

코드 스니펫의 시작 부분에 예제 파일 이름을 참조하는 것이 도움이 될 수 있습니다. 예를 들어, # wagtail_hooks.py 또는 // js/my-custom.js 와 같습니다.

CSP (콘텐츠 보안 정책) 준수¶

외부 소스나 사용자 정의 스크립트에서 JavaScript를 추가할 때, 교차 사이트 스크립팅(XSS)과 같은 보안 취약점을 방지하기 위해 CSP 준수를 확인하세요.

가능한 한\ mark_safe\ 사용을 피하고, format_html\ 을 사용하며, 인라인\ <script>\ 사용 대신 스크립트를 안전하게 관리하기 위해 외부 파일을 로드하는 예제를 사용하세요.

접근성 준수¶

모든 예제가 접근 가능하고 접근성 표준(예: WCAG, ATAG)을 준수하는지 확인하세요.

대화형 컴포넌트의 경우, 적절한 키보드 탐색 및 스크린 리더 지원을 보장하세요. 동적 콘텐츠나 효과(애니메이션 또는 알림 등)를 만들 때, 사용자가 이러한 기능을 일시 중지, 중지 또는 조정할 수 있는 옵션을 제공하세요.

필요한 경우, 예제가 접근성을 준수하지 않으며 채택하기 전에 추가적인 고려가 필요하다는 점을 명시적으로 언급하세요.