[[https://pypi.org/project/docwriter/]]

===== FreeType 문서 작성기 =====

Docwriter는 FreeType 헤더 파일에서 마크다운 문서를 추출하고 빌드하는 FreeType 라이브러리용 API 문서 생성기입니다.

==== 설치 ====

''pip install docwriter''를 실행합니다(자동화된 ''virtualenv'' 사용법은 아래 (4)를 참조하세요). 실행하려면 __Python >= 3.5__가 필요합니다.

==== 문서 생성 단계 ====

1. ''pip''를 사용하여 ''docwriter''가 설치되었는지 확인합니다.

2. [[https://gitlab.freedesktop.org/freetype/freetype.git|여기]]에서 프리타입 리포지토리를 복제합니다.

3. FreeType 빌드 시스템을 사용하여 문서를 생성할 수 있습니다.

<code bash>
sh autogen.sh
./configure
make refdoc
</code>

4. 또는 1단계와 make 대상을 ''make refdoc-venv''로 대체할 수 있습니다. 이렇게 하면 모든 요구 사항이 별도의 가상 환경에 자동으로 설치됩니다. 가상 환경 사용에 대한 자세한 내용은 [[https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/docs/README|여기]]에서 확인할 수 있습니다.

==== 개발 사용 ====

1.이 리포지토리를 복제합니다.

2.[[https://gitlab.freedesktop.org/freetype/freetype.git|여기]]에서 프리타입 리포지토리를 복제합니다.

3. 사용 중인 환경에서 ''pip install -r requirements.txt''를 실행합니다(''virtualenv'' 권장).

4. ''include/'' 디렉터리를 ''freetype''에서 ''docwriter''로 복사합니다.

5. ''docwriter'' 디렉토리에서 실행합니다:

<code bash>
python -m docwriter                      \
        --prefix=ft2                     \
        --title=FreeType-2.13.1          \
        --site=reference                 \
        --output=./docs                  \
        ./include/freetype/*.h           \
        ./include/freetype/config/*.h    \
        ./include/freetype/cache/*.h
</code>

마크다운 파일은 ''docs/markdown/''에 생성됩니다. 정적 사이트는 ''docs/''에서 ''mkdocs'' 빌드를 실행하여 빌드할 수 있습니다. [[https://www.mkdocs.org/getting-started/#building-the-site|여기]]에서 Mkdocs에 대해 자세히 알아보세요.

==== 사용 정보 ====

<code>
docwriter [-h] [-t T] -o DIR [-p PRE] [-s DIR] [-q | -v] files [files ...]

DocWriter Usage information

positional arguments:
  files                 list of source files to parse, wildcards are allowed

optional arguments:
  -h, --help            show this help message and exit
  -t T, --title T       set project title, as in '-t "My Project"'
  -o DIR, --output DIR  set output directory, as in '-o mydir'
  -p PRE, --prefix PRE  set documentation prefix, as in '-p ft2'
  -s DIR, --site DIR    set 'site_dir' in mkdocs.yml [default=site]
  -q, --quiet           run quietly, show only errors
  -v, --verbose         increase output verbosity
</code>

==== 테스트 실행 ====

지원되는 모든 Python 버전에서 테스트하려면 다음과 같이 하세요:

1. ''tox''가 설치되어 있는지 확인합니다:

<code bash>
pip install tox
</code>

2. 테스트를 실행해야 하는 모든 Python 버전이 설치되어 있는지 확인합니다.

3. 테스트를 실행합니다.

<code bash
tox
</code>

특정 테스트를 실행하려면 ''-e'' 인수를 사용합니다. 예를 들면 다음과 같습니다.

<code bash>
tox -e py37,py38
</code>

위의 코드는 Python 3.7 및 3.8에서만 테스트를 실행합니다(설치되어 있다고 가정). 사용 가능한 모든 환경은 [[https://pypi.org/project/docwriter/tox.ini|tox.ini]]를 참조하세요.

특정 tox 환경 실행에 대한 자세한 내용은 [[https://tox.readthedocs.io/en/latest/example/general.html#selecting-one-or-more-environments-to-run-tests-against|여기]]에서 확인할 수 있습니다.

==== 회귀 테스트 ====

회귀 테스트에는 인터넷 액세스, ''git'' 및 기타 FreeType [[https://gitlab.freedesktop.org/freetype/freetype/-/blob/master/README.git|빌드 종속성]]이 필요하며 시간이 오래 걸립니다. 이러한 테스트는 주로 Gitlab CI에서 실행하기 위한 것이지만 로컬에서도 실행할 수 있습니다:

<code bash>
tox -e regression
</code>

==== 라이센스 ====

이 라이브러리는 [[https://www.freetype.org/license.html|FreeType License]]에 따라 라이센스가 부여됩니다.

==== 역사 ====

이 라이브러리는 원래 데이비드 터너가 HTML로 문서를 수집하고 제시하는 ''docmaker''로 작성했습니다. 이후 여러 출력 형식을 허용하는 주요 리팩터링을 포함하여 여러 번 수정되었습니다. 현재 ''docwriter''는 가장 큰 규모의 재작성 작업으로, 유연성, 가독성, 유지보수성 및 사용성을 높이기 위해 많은 변경 사항과 추가 사항이 포함되어 있습니다.