# Django 6.0.7 문서

# 문서 작성하기

우리는 문서의 일관성과 가독성을 매우 중요하게 여깁니다. Django는 저널리즘 환경에서 만들어졌기 때문입니다! 그래서 문서를 코드처럼 다루고, 가능한 한 자주 개선하려고 합니다.

문서 변경은 다음 두 가지 형태로 이뤄집니다.

- 일반적인 개선: 오탈자 수정, 명료한 문장과 더 많은 예제를 통한 오류 수정 및 예제 개선.

- 새로운 기능: 최종 릴리스 이후에 프레임워크에 추가된 기능에 대한 문서화.

이 절에서는 저자들이 어떻게 유용하고도 오류를 적게 일으키는 방식으로 문서 변경을 다루는지 설명합니다.

## Django 문서 작성 과정

Django 문서는 https://docs.djangoproject.com/에서 HTML로 제공되지만, 최대한의 유연성을 위해 reStructuredText 마크업 언어로 작성된 일반 텍스트 파일 모음으로 편집합니다.

우리는 저장소의 개발 버전에서 작업합니다. 해당 버전에는 최신 문서가 포함되어 있고, 코드도 마찬가지로 최신 상태이기 때문입니다.

문서 수정과 개선 사항도 머저의 재량에 따라 마지막 릴리스 브랜치에 백포트됩니다. 이는 마지막 릴리스의 문서를 최신 상태이면서 정확하게 유지하는 것이 유리하기 때문입니다(버전 간 차이점 참고).

Django 문서는 docutils__를 기반으로 하는 Sphinx__ 문서화 시스템을 사용합니다. Sphinx는 가벼운 형식의 일반 텍스트 문서를 HTML, PDF, 기타 여러 형식으로 변환해줍니다.

Sphinx에는 reStructuredText를 HTML과 PDF 등 다른 형식으로 변환하는 `sphinx-build` 명령이 있습니다. 이 명령은 설정할 수 있지만, Django 문서에는 `make html` 명령으로 더 간단하게 실행할 수 있도록 하는 ``Makefile``이 포함되어 있습니다.

## 이 문서의 구조

문서는 여러 범주로 나뉩니다.

- 튜토리얼은 독자로 하여금 차근차근 따라 하면서 뭔가 만들어 볼 수 있도록 해줍니다.

  튜토리얼에서 가장 중요한 것은 독자가 최대한 빠르게 유용한 것을 만들어 봄으로써 자신감을 갖도록 하는 것입니다.

  우리가 해결하려는 문제의 본질을 설명하여, 무엇을 이루고자 하는지 독자가 이해할 수 있도록 합니다. 동작 원리를 설명하는 데 꼭 얽매일 필요는 없습니다. 무엇을 설명하는 지보다 독자가 무엇을 하는 지가 더 중요합니다. 경우에 따라서는 먼저 작업을 진행한 뒤, 나중에 그 과정을 되짚어 설명하는 것이 도움이 될 수 있습니다.

- 주제 가이드는 개념 또는 주제를 고수준에서 설명하는 것을 목적으로 합니다.

  참고 자료에 있는 내용을 반복하지 말고 링크를 거세요. 예제를 사용하고, 매우 기초적인 내용에 대한 설명을 아끼지 마세요. 그런 설명을 필요로 하는 사람이 있을 지 모릅니다.

  해당 주제를 처음 접하는 사람들을 위해 배경 지식을 설명하는 것은 그들이 이미 알고 있는 것과 연결하는 데 도움이 됩니다.

- :doc:`참조 가이드 </ref/index>`는 API에 대한 기술적 참고 자료를 제공합니다. 또한 Django의 내부 동작 방식을 설명하고, 그 사용법을 안내합니다

  참고 자료는 주제에 집중해야 합니다. 독자가 이미 기본 개념을 알고 있되 Django에서 그것을 어떻게 다루는지에 대한 설명이 필요할 것으로 가정하세요.

  참조 가이드는 일반적인 설명을 위한 것이 아닙니다. 기본 개념에 대해 설명하고 있다고 느껴지면, 그것을 주제 가이드로 옮기기 바랍니다.

- How-to 가이드는 주요한 주제에 있어서 독자가 따라할 수 있는 레시피입니다.

  how-to 가이드에서는 사용자가 달성하고자 하는 것이 중요합니다. how-to에서는 Django의 내부 구현에 대한 세부 사항보다는 결과물을 도출하는 데 집중해야 합니다.

  how-to 가이드는 튜토리얼보다 수준이 높으며, 독자가 Django의 동작 원리에 대한 지식이 있을 것으로 간주합니다. 독자가 이미 튜토리얼을 읽은 것으로 간주하고, 같은 내용을 반복하지 말고 관련 튜토리얼에 대한 참조를 제공하세요.

## 문서 기여를 시작하는 방법

### 로컬 컴퓨터에 Django 저장소 복제하기

문서 기여를 시작하려면 소스 코드 저장소에서 Django의 개발 버전을 가져오세요(Installing the development version 참고).

/ 

    $ git clone https://github.com/django/django.git

    ...\> git clone https://github.com/django/django.git

이러한 변경 사항을 제출할 계획이라면 Django 저장소를 포크한 뒤 해당 포크를 복제하는 것이 도움이 될 수 있습니다.

### 가상 환경을 설정하고 의존성을 설치하기

가상 환경을 생성하고 활성화한 다음, 의존성을 설치합니다.

    $ python -m venv .venv
    $ source .venv/bin/activate
    $ python -m pip install -r docs/requirements.txt

### 로컬에서 문서 빌드하기

`docs` 디렉토리에서 HTML 문서를 빌드할 수 있습니다.

/ 

    $ cd docs
    $ make html

    ...\> cd docs
    ...\> make.bat html

로컬에서 빌드한 문서는 ``_build/html/index.html``에서 확인할 수 있으며 웹 브라우저에서 열어볼 수 있습니다. 다만 `docs.djangoproject.com <https://docs.djangoproject.com/>`_의 문서와는 테마가 다르게 표시됩니다. 이는 정상입니다. 로컬 환경에서 변경 사항이 잘 보인다면 웹사이트에서도 잘 보일 것입니다.

#### Automating documentation rebuilds

sphinx-autobuild can be used to automatically rebuild the documentation and reload the documentation page in the browser whenever a file changes. To enable auto-reloading:

1. Install the package:

   / 

       $ python -m pip install sphinx-autobuild

       ...\> py -m pip install sphinx-autobuild

2. From the `docs` directory, run one of the following commands:

   - On Linux and macOS:

         $ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html

   - On Windows (Command Prompt):

         ...\> set SPHINXBUILD=sphinx-autobuild
         ...\> set SPHINXOPTS=--open-browser --delay 0
         ...\> make html

   - On Windows (PowerShell):

         PS> $env:SPHINXBUILD="sphinx-autobuild"
         PS> $env:SPHINXOPTS="--open-browser --delay 0"
         PS> make html

   Alternatively, `sphinx-autobuild` can be invoked directly:

   / 

       $ sphinx-autobuild . _build/html --open-browser --delay 0

       ...\> sphinx-autobuild . _build\html --open-browser --delay 0

The auto-reloader can be stopped with `Ctrl+C`.

### 문서 수정하기

소스 파일은 `docs/` 디렉토리에 있는 `.txt` 파일입니다.

이러한 파일은 reStructuredText 마크업 언어로 작성되어 있습니다. 마크업에 대해 알아보려면 :ref:`reStructuredText reference <sphinx:rst-index>`를 참고하세요.

예를 들어 이 페이지를 수정하려면 docs/internals/contributing/writing-documentation.txt 파일을 수정한 다음 ``make html``로 HTML을 다시 빌드합니다.

### 문서 품질 점검

Django의 문서 품질을 유지하기 위해 여러 검사가 수행되며, 여기에는 spelling, code block formatting, documentation style 등이 포함됩니다.

이러한 점검은 CI에서 자동으로 실행되며 문서 변경 사항이 병합되기 전에 반드시 통과해야 합니다. 또한 단일 명령으로 로컬에서도 실행할 수 있습니다.

/ 

    $ make check

    ...\> make.bat check

이 명령은 현재의 모든 점검을 실행하며, 향후 추가되는 새로운 점검도 포함합니다.

#### 철자 확인

Before you commit your docs, it’s a good idea to run the spelling checker. You’ll need to install sphinxcontrib-spelling first. The spell checker also requires a system-level spell checking backend such as Aspell. Then from the `docs` directory, run:

/ 

    $ make spelling

    ...\> make.bat spelling

잘못된 단어가 있을 경우 해당 파일과 줄 번호와 함께 ``_build/spelling/output.txt``에 저장됩니다.

False Positive(실제로 정확한 오류 출력)가 발생하는 경우 다음 중 하나를 수행합니다.

- 인라인 코드나 브랜드/기술 이름은 백틱 두 개(``)로 감쌉니다.

- 철자 검사기가 인식하는 동의어를 찾습니다.

- 사용 중인 단어가 정확하다고 확신하는 경우에만 “docs/spelling_wordlist”에 추가합니다(목록은 알파벳 순으로 유지).

#### 코드 블록 형식 점검

모든 Python 코드 블록은 blacken-docs 자동 포맷터를 사용해 형식을 맞춰야 합니다. 이는 :ref:`pre-commit hook <coding-style-pre-commit>`가 설정되어 있으면 자동으로 실행됩니다.

이 점검은 수동으로도 실행할 수 있습니다. `blacken-docs``가 설치되어 있다면 ``docs` 디렉토리에서 다음 명령을 실행하세요.

/ 

    $ make black

    ...\> make.bat black

포맷터는 문제를 터미널에 출력하여 보고하며, 가능한 경우 코드 블록의 형식을 다시 맞춥니다.

#### 문서 린트 점검

Django의 문서는 :pypi:`sphinx-lint`를 사용해 reStructuredText 스타일과 형식 관련 문제를 점검합니다. 이를 통해 불필요한 탭 문자, 줄 끝 공백, 과도한 줄 길이와 같은 문제를 비롯해 유사한 형식 문제를 찾아낼 수 있습니다.

`sphinx-lint``이 설치되면 ``docs` 디렉토리에서 다음 명령으로 점검을 실행할 수 있습니다.

/ 

    $ make lint

    ...\> make.bat lint

이 명령은 `path:line: message` 형식으로 위반 사항을 터미널에 출력합니다. 문제가 발생한 경우:

- 메시지를 읽고 표시된 문제를 수정하세요(예: 줄 끝 공백 제거, 백틱 조정, 탭을 공백으로 변환).

- 긴 줄의 경우 텍스트를 새 줄로 나누거나 긴 인라인 링크를 이름 있는 참조로 바꾸는 것을 고려하세요. 사용자 정의 줄 길이 점검은 제목, 표, 긴 링크와 같은 일반적인 오탐은 이미 제외하도록 되어 있습니다.

### 링크체크

문서의 링크는 깨지거나 변경되어 더 이상 표준 링크가 아닐 수 있습니다. Sphinx는 문서 내 링크가 정상적으로 작동하는지 확인할 수 있는 빌더를 제공합니다. `docs` 디렉토리에서 다음 명령을 실행하세요.

/ 

    $ make linkcheck

    ...\> make.bat linkcheck

출력 결과는 터미널에 표시되며, `_build/linkcheck/output.txt` 및 ``_build/linkcheck/output.json``에서도 확인할 수 있습니다.

경고

이 명령을 실행하려면 인터넷 연결이 필요하며, 완료까지 몇 분 정도 걸립니다. 이는 문서에 포함된 모든 링크를 검사하기 때문입니다.

상태가 “작동 중”인 항목은 정상이며, “선택 취소됨” 또는 “무시됨” 항목은 확인할 수 없거나 구성의 무시 규칙과 일치하기 때문에 건너뜁니다.

상태가 “broken”인 항목은 수정해야 합니다. 상태가 “redirected”인 항목은 정식 경로를 가리키도록 업데이트해야 할 수 있습니다(예: `http://` → `https://``로 스킴이 변경된 경우). 다만 일부 경우에는 "redirected" 링크를 업데이트하지 않는 것이 좋습니다. 예를 들어 항상 문서의 최신 또는 안정 버전을 가리키도록 하는 재작성의 경우(예: ``/en/stable/` → `/en/3.2/`)가 이에 해당합니다.

## 문체

“세션 쿠키를 가진 사용자”와 같이 가상의 인물을 지칭할 때는 성별을 드러내지 않는 대명사(they/their/them)를 사용해야 합니다. 다음 대신:

- he 또는 she 대신 they를 사용합니다.

- him 또는 her 대신 them을 사용합니다.

- his 또는 her 대신 their를 사용합니다.

- his 또는 hers 대신 theirs를 사용합니다.

- himself 또는 herself 대신 themselves를 사용합니다.

작업이나 작업 과정의 난이도를 낮춰 보이게 하는 표현(예: “easily”, “simply”, “just”, “merely”, “straightforward” 등)은 사용을 피하세요. 실제 사용자의 경험은 예상과 다를 수 있으며, 안내된 단계가 “straightforward”하거나 “simple”하다고 느껴지지 않을 경우 사용자가 불편을 겪을 수 있습니다.

## 공통적인 용어

다음은 문서에서 공통적으로 사용되는 용어에 대한 지침입니다.

- Django – 프레임워크를 지칭할 때에는 첫 글자를 대문자로 하여 Django로 표기합니다. Python 코드와 djangoproject.com 로고에서만 소문자를 사용합니다.

- email – 하이픈을 넣지 않습니다.

- HTTP – 예상 발음이 “Aitch Tee Tee Pee”이므로 관사는 “a”가 아니라 “an”을 사용해야 합니다.

- MySQL, PostgreSQL, SQLite

- SQL – SQL을 가리킬 때, 그 발음은 “시퀄”이 아니라 “에스큐엘”로 합니다. 따라서 “Returns an SQL expression”과 같은 표현에서 “SQL” 앞에는 “a”가 아닌 “an”이 옵니다.

- Python – 언어를 가리킬 때에는 첫 글자를 대문자로 하여 Python으로 표기합니다.

- realize, customize, initialize 등. – 미국식으로 “ize”를 붙이며, “ise”는 붙이지 않습니다.

- subclass – 하이픈이 없는 하나의 단어로, 동사(“subclass that model”) 또는 명사(“create a subclass”)입니다.

- the web, web framework – 대문자로 표기하지 않습니다.

- website – 대문자 없이 한 단어로 씁니다.

## Django 관련 용어

- model – 대문자가 아닙니다.

- template – 대문자가 아닙니다.

- URLconf – 처음 세 글자를 대문자로 하며, “conf”와의 사이에 공백을 두지 않습니다.

- view – 대문자가 아닙니다.

## reStructuredText 파일 안내

이러한 가이드라인은 reST(reStructuredText) 문서의 형식을 규정합니다.

- 섹션 제목에서는 첫 단어와 고유명사만 대문자로 표기합니다.

- 문서는 80자 너비로 줄바꿈합니다. 다만 코드 예시를 두 줄로 나누면 가독성이 크게 떨어지는 경우나 기타 적절한 이유가 있는 경우는 예외로 합니다.

- 문서를 작성하고 수정할 때 가장 중요한 점은 가능한 한 많은 시맨틱 마크업을 추가하는 것입니다. 따라서:

      Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...

  Isn’t nearly as helpful as:

      Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...

  이는 Sphinx가 후자의 경우에 적절한 링크를 생성해 독자에게 큰 도움이 되기 때문입니다.

  대상 앞에 ``~``(물결표)를 붙이면 해당 경로의 마지막 부분만 표시할 수 있습니다. 따라서 ``:mod:`~django.contrib.auth```는 “auth”라는 제목의 링크로 표시됩니다.

- Python과 Sphinx의 문서를 참조하려면 :mod:`~sphinx.ext.intersphinx`를 사용하세요.

- 리터럴 블록이 하이라이트되도록 `.. code-block:: <lang>``을 추가하세요. 다만 ``::` (콜론 두 개)를 사용한 자동 하이라이팅을 사용하는 것을 권장합니다. 이 방법은 코드에 일부 잘못된 구문이 포함되어 있더라도 하이라이트되지 않는다는 장점이 있습니다. 예를 들어 ``.. code-block:: python``을 추가하면 잘못된 구문이 있어도 강제로 하이라이트됩니다.

- 가독성을 높이기 위해 `.. note::` 대신 ``.. admonition:: Descriptive title``을 사용하세요. 이러한 박스는 필요할 때만 사용하세요.

- 다음과 같은 제목 스타일을 사용하세요.

      ===
      One
      ===

      Two
      ===

      Three
      -----

      Four
      ~~~~

      Five
      ^^^^

- Request for Comments(RFC)를 참조하려면 `:rfc:<rfc>`를 사용하고 가능하다면 관련 섹션으로 링크하세요. 예를 들어 ``RFC 2324 Section 2.3.2`` 또는 ``:rfc:`Custom link text <2324#section-2.3.2>```을 사용할 수 있습니다.

- Python Enhancement Proposal(PEP)를 참조하려면 `:pep:<pep>`를 사용하고 가능하다면 관련 섹션으로 링크하세요. 예를 들어 ``PEP 20#easter-egg`` 또는 ``:pep:`Easter Egg <20#easter-egg>```을 사용할 수 있습니다.

- 코드 예시에서 값이 따옴표로 감싸진 경우가 아니라면 MIME 유형을 참조할 때 :rst:role:`:mimetype:<mimetype>`을 사용하세요.

- 환경 변수를 참조하려면 `:envvar:<envvar>`를 사용하세요. 또한 해당 환경 변수에 대한 문서 참조를 :rst:dir:`.. envvar:: <envvar>`를 사용하여 정의해야 할 수도 있습니다.

- Common Vulnerabilities and Exposures(CVE) 식별자를 참조하려면 `:cve:<cve>`를 사용하세요. 예를 들어 ``:cve:`2019-14232```를 사용할 수 있습니다.

- `.. class::`, `.. method::`, ``.. attribute::``와 같은 `Sphinx directives`__를 사용하여 Python 객체(클래스, 메서드, 속성 등)를 문서화할 때는 모든 콘텐츠를 올바르게 렌더링하고 자동 목차 생성과 같은 기능을 지원할 수 있도록 적절히 들여써야 합니다.

  다음 규칙을 따르세요.

  - 디렉티브 자체는 들여쓰기 없이 왼쪽 여백에 맞춥니다.

  - 디렉티브 아래의 모든 설명 텍스트는 공백 4칸으로 들여써야 합니다.

  - 여러 줄로 된 설명은 들여쓰기를 동일하게 유지해야 합니다.

  - 중첩된 디렉티브(예: 클래스 내부의 메서드)는 계층 구조를 유지하기 위해 추가로 공백 4칸을 들여써야 합니다.

  - 필드 목록(`:param:`, `:returns:` 등)은 디렉티브의 콘텐츠 수준에 맞게 정렬해야 합니다.

  예제:

      .. class:: MyClass

          A brief description of the class.

          .. method:: my_method(arg1, arg2)

              Method description.

              :param arg1: Description of the first parameter
              :param arg2: Description of the second parameter

          .. attribute:: my_attribute

              Attribute description.

## Django 전용 마크업

Sphinx’s built-in markup 외에도 Django 문서에서는 몇 가지 설명 단위를 추가로 정의합니다.

- 설정:

      .. setting:: INSTALLED_APPS

  설정에 연결하려면 `:setting:`INSTALLED_APPS`` 을 사용하십시오.

- 템플릿 태그:

      .. templatetag:: regroup

  링크하기 위해서, ``:ttag:`regroup```를 이용하십시오.

- 템플릿 필터:

      .. templatefilter:: linebreaksbr

  연결하려면``:tfilter:`linebreaksbr```를 이용하십시오.

- 필드 조회 조건(예: `Foo.objects.filter(bar__exact=whatever)`):

      .. fieldlookup:: exact

  연결하려면````:lookup:`exact``````를 이용하십시오.

- `django-admin` 명령:

      .. django-admin:: migrate

  연결하려면``:djadmin:`migrate```를 이용하십시오.

- `django-admin` 명령줄 옵션:

      .. django-admin-option:: --traceback

  링크하려면 ```command_name --traceback```을 사용하세요(또는 ``–verbosity``와 같이 모든 명령에서 공통으로 사용하는 옵션의 경우 ``command_name``은 생략할 수 있습니다).

- Trac 티켓에 대한 링크(일반적으로 패치 릴리스 노트에서 주로 사용됨):

      :ticket:`12345`

Django’s documentation uses a custom `console` directive for documenting command-line examples involving `django-admin`, `manage.py`, `python`, etc. In the HTML documentation, it renders a two-tab UI, with one tab showing a Unix-style command prompt and a second tab showing a Windows prompt.

예를 들어 다음과 같은 부분을 바꿀 수 있습니다.

    use this command:

    .. code-block:: console

        $ python manage.py shell

with this one:

    use this command:

    .. console::

        $ python manage.py shell

다음 두 가지를 주목하십시오.

- 일반적으로 `.. code-block:: console` 지시문의 항목을 대체합니다.

- 코드 예시의 실제 내용은 변경할 필요가 없습니다. 계속해서 Unix 계열 환경을 기준으로 작성하세요(예: `'$'` 프롬프트 기호, `'/'` 파일 시스템 경로 구분자 등).

위의 예제에서는 두 개의 탭이 있는 코드 예제 블록을 렌더링합니다. 첫 번째 항목은 다음과 같습니다.

    $ python manage.py shell

(``.. code-block:: console``에서 렌더링한 변경 사항은 없습니다.)

두 번째 항목은 다음과 같습니다.

    ...\> py manage.py shell

## 새로운 기능을 문서화합니다.

새로운 기능에 대한 당사의 정책은 다음과 같습니다.

> 새로운 기능에 대한 모든 문서는 해당 기능이 Django 개발 버전에서만 사용 가능함을 명확히 드러내는 방식으로 작성되어야 합니다. 문서 독자는 개발 버전이 아니라 최신 릴리스를 사용한다고 가정하세요.

새로운 기능을 표시하는 권장 방식은 해당 기능의 문서 앞에 “`.. versionadded:: X.Y`”를 추가하는 것입니다. 그 다음에는 필수로 빈 줄을 한 줄 넣고, 선택적으로 설명(들여쓰기)을 덧붙일 수 있습니다.

General improvements or other changes to the APIs that should be emphasized should use the “`.. versionchanged:: X.Y`” directive (with the same format as the `versionadded` mentioned above).

이러한 `versionadded` 및 `versionchanged` 블록은 자체적으로 독립된 형태를 갖춰야 합니다. 즉, 이러한 주석은 두 번의 릴리스 동안만 유지되므로 주변 텍스트를 다시 정리하거나 들여쓰기를 수정하거나 편집할 필요 없이 주석과 그 내용만 제거할 수 있어야 합니다. 예를 들어, 새로 추가되거나 변경된 기능에 대한 전체 설명을 블록 안에 넣는 대신 다음과 같이 작성하세요.

    .. class:: Author(first_name, last_name, middle_name=None)

        A person who writes books.

        ``first_name`` is ...

        ...

        ``middle_name`` is ...

        .. versionchanged:: A.B

            The ``middle_name`` argument was added.

변경된 주석 노트를 맨 위가 아닌 섹션 맨 아래에 배치합니다.

또한 `versionadded` 또는 `versionchanged` 블록 외부에서 특정 Django 버전을 언급하는 것은 피하세요. 블록 내부에서도 이러한 표기는 각각 “New in Django A.B:”와 “Changed in Django A.B”로 렌더링되므로, 별도로 버전을 명시하는 것은 대체로 불필요합니다.

함수, 속성 등이 추가된 경우에는 다음과 같이 `versionadded` 표기를 사용해도 됩니다.

    .. attribute:: Author.middle_name

        .. versionadded:: A.B

        An author's middle name.

시기가 되면 들여쓰기를 변경하지 않고도 `.. versionadded:: A.B` 표기를 제거할 수 있습니다.

## 이미지 최소화

가능한 경우 이미지 압축을 최적화합니다. PNG 파일의 경우 OptiPNG 및 Advanced를 사용합니다.COMP의 ‘’advpng’’:

/ 

    $ cd docs
    $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
    $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`

    ...\> cd docs
    ...\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\_build\*" -name "*.png"`
    ...\> advpng -z4 `find . -type f -not -path ".\_build\*" -name "*.png"`

이 버전은 OptiPNG 버전 0.7.5를 기반으로 합니다. 구 버전에서는 “-스트라이프 올” 옵션이 상실되는 것에 대해 불평할 수도 있습니다.

## 예제:

이 모든 것이 어떻게 서로 들어맞는지에 대한 간단한 예제를 보려면 다음 가상 예를 고려해 보십시오.

- 먼저 ‘’참조/설정’’입니다.txt document 문서의 전체 레이아웃은 다음과 같습니다.

      ========
      Settings
      ========

      ...

      .. _available-settings:

      Available settings
      ==================

      ...

      .. _deprecated-settings:

      Deprecated settings
      ===================

      ...

- 다음은 ‘’주제/설정’’입니다.txt 문서에는 다음과 같은 내용이 포함될 수 있습니다.

      You can access a :ref:`listing of all available settings
      <available-settings>`. For a list of deprecated settings see
      :ref:`deprecated-settings`.

      You can find both in the :doc:`settings reference document
      </ref/settings>`.

  다른 문서 전체에 연결하려는 경우에는 Sphinx의 `doc` 상호 참조를 사용하고, 문서 내의 특정 위치에 연결하려는 경우에는 :rst:role:`ref`를 사용합니다.

- 그런 다음 설정에 주석을 달 수 있습니다.

      .. setting:: ADMINS

      ADMINS
      ======

      Default: ``[]`` (Empty list)

      A list of all the people who get code error notifications...

  이는 아래 제목을 `ADMINS` 설정의 “기본 참조” 대상으로 마크업합니다. 따라서 ``ADMINS``를 언급할 때마다 ``:setting:`ADMINS```로 참조할 수 있습니다.

기본적으로 모든 것이 서로 맞아떨어집니다.

## 번역 문서

참조:ref:문서를 다른 언어로 번역하려면 “장고 문서 현지화”를 참조하십시오.

## ‘’dango-admin’ man 페이지

Sphinx는 django-admin 명령에 대한 매뉴얼 페이지를 생성할 수 있습니다. 이는 ``docs/conf.py``에서 설정됩니다. 다른 문서 출력과 달리, 이 man 페이지는 ``docs/man/django-admin.1``로 Django 저장소와 릴리스에 포함되어야 합니다. 이 파일은 문서를 업데이트할 때 별도로 갱신할 필요가 없으며, 릴리스 과정의 일부로 한 번만 갱신됩니다.

업데이트된 man 페이지를 생성하려면 `docs` 디렉토리에서 다음을 실행하세요.

/ 

    $ make man

    ...\> make.bat man

새로운 man 페이지는 ``docs/_build/man/django-admin.1``에 생성됩니다.