이 페이지의 내용

Guidedog / 문서 0.2.0

설정 참조

Guidedog 프로젝트는 루트의 conf.toml 로 설정합니다. 설정은 선언형 TOML 데이터이며 임의의 코드를 실행하지 않습니다.

많은 설정 키가 Sphinx의 conf.py 변수에 대응하므로 guidedog migrate conf.py 로 이전을 도울 수 있습니다.

최소 설정

기본 메타데이터만으로 프로젝트를 시작할 수 있습니다. 생략한 설정에는 기본값을 사용합니다.

project = "Field Notes"
author = "Your Name"
version = "1.0"
release = "1.0.0"
language = "en"
root_doc = "index"
source_suffix = [".rst", ".md"]
templates_path = ["_templates"]
html_static_path = ["_static"]
pdf_paper_size = "a4"

프로젝트 메타데이터

표 8 메타데이터 옵션

키	형식	기본값	설명
project	문자열	"Python"	사람이 읽을 수 있는 프로젝트 이름입니다.
author	문자열	""	저자 또는 조직 이름입니다.
copyright	문자열	""	페이지 하단에 표시할 저작권 문구입니다.
version	문자열	""	짧은 버전 번호입니다. 예: "1.0".
release	문자열	""	alpha나 beta 식별자를 포함한 전체 버전 문자열입니다. 예: "1.0.0b1".
language	문자열	"en"	조판, 하이픈 처리, 번역에 사용할 ISO 언어 코드입니다. 예: "de", "zh_CN".
today	문자열	""	날짜를 직접 지정합니다. 생략하면 현재 날짜를 today_fmt 으로 표시합니다.
today_fmt	문자열	""	문서 날짜의 형식 문자열입니다.

일반 옵션

표 9 검색 및 파싱 옵션

키	형식	기본값	설명
root_doc	문자열	"index"	최상위 목차로 사용할 문서입니다.
source_suffix	배열	[".rst"]	문서 소스로 인식할 파일 확장자입니다.
exclude_patterns	배열	[]	소스 검색에서 제외할 디렉터리와 파일의 glob 패턴입니다.
include_roots	배열	[]	소스를 포함할 수 있도록 허용한 외부 루트 디렉터리입니다.
templates_path	배열	[]	HTML과 PDF 템플릿 디렉터리입니다. 내장 템플릿보다 먼저 검색합니다.
extensions	배열	[]	활성화할 내장 Sphinx 확장입니다. 예: "sphinx.ext.autodoc".
primary_domain	문자열	"py"	접두사가 없는 지시문과 역할의 기본 도메인입니다. 예: "py", "c", "odin".
highlight_language	문자열	"default"	코드 블록에 언어를 지정하지 않았을 때 사용할 기본 언어입니다.
pygments_style	문자열	""	밝은 테마에 사용할 Pygments 구문 강조 스타일입니다.
pygments_dark_style	문자열	""	어두운 테마에 사용할 구문 강조 스타일입니다.
smartquotes	불리언	true	곧은 따옴표와 대시를 조판용 문장 부호로 바꿉니다.
rst_prolog	문자열	""	각 문서 앞에 붙일 reStructuredText 조각입니다.
rst_epilog	문자열	""	각 문서 끝에 붙일 reStructuredText 조각입니다.

번호와 수식

표 10 번호 옵션

키	형식	기본값	설명
numfig	불리언	false	활성화하면 그림, 표, 코드에 자동으로 번호를 붙입니다.
numfig_secnum_depth	정수	1	그림 번호에 포함할 제목 깊이입니다. 1 이면 Fig. 2.1 형식이 됩니다.
numfig_format	테이블	아래 참고	"figure", "table", "code-block" 의 번호 접두사 형식입니다.
math_number_all	불리언	false	모든 독립 수식에 자동으로 번호를 붙입니다.
math_eqref_format	문자열	"({number})"	:eq: 수식 참조의 형식 문자열입니다.
mathjax_path	문자열	URL	MathJax JavaScript 파일의 CDN URL 또는 로컬 경로입니다.

numfig_format 기본값:

[numfig_format]
figure = "Fig. %s"
table = "Table %s"
code-block = "Listing %s"
section = "Section %s"

진단과 엄격한 검사

표 11 진단 옵션

키	형식	기본값	설명
nitpicky	불리언	false	해결되지 않은 상호 참조와 잘못된 대상을 경고합니다.
nitpick_ignore	배열	[]	엄격한 참조 검사에서 제외할 [type, target] 쌍의 배열입니다.
suppress_warnings	배열	[]	보고하지 않을 경고 범주 코드입니다.
keep_warnings	불리언	false	게시한 문서에 경고를 포함합니다.

HTML 출력 옵션

표 12 HTML 옵션

키	형식	기본값	설명
html_theme	문자열	"guidedog"	HTML 생성에 사용할 테마입니다.
html_theme_options	테이블	{}	HTML 테마에 전달할 키-값 옵션입니다.
html_title	문자열	자동 생성	브라우저 탭에 표시할 제목입니다.
html_short_title	문자열	자동 생성	이동 경로에 사용할 짧은 제목입니다.
html_logo	문자열	""	소스 디렉터리를 기준으로 한 프로젝트 로고 경로입니다.
html_favicon	문자열	""	파비콘 파일 경로입니다.
html_static_path	배열	[]	출력의 _static/ 으로 복사할 디렉터리입니다.
html_extra_path	배열	[]	변환 없이 출력 루트로 복사할 디렉터리입니다.
html_css_files	배열	[]	HTML 페이지에서 불러올 사용자 CSS 파일 이름입니다.
html_js_files	배열	[]	HTML 페이지에서 불러올 사용자 JavaScript 파일 이름입니다.
html_permalinks	불리언	true	단락과 절에 고정 링크를 붙입니다.
html_permalinks_icon	문자열	"¶"	고정 링크에 사용할 기호나 텍스트입니다.
html_baseurl	문자열	""	사이트맵과 메타데이터에 사용할 정규 기본 URL입니다.
html_context	테이블	{}	Jinja 템플릿에 전달할 사용자 변수 사전입니다.
html_additional_pages	테이블	{}	추가로 렌더링할 페이지입니다: { "page_name" = "template.html" }.

PDF와 Typst 옵션

표 13 PDF 옵션

키	형식	기본값	설명
pdf_paper_size	문자열	"a4"	용지 크기는 "a4" 또는 "us-letter" 입니다.
pdf_logo	문자열	""	책 표지에 사용할 로고 경로입니다.
pdf_toplevel_sectioning	문자열	"chapter"	책의 최상위 구분에 대응할 절 수준입니다: "chapter" 또는 "part".
pdf_show_urls	문자열	"no"	인쇄본의 URL 표시 방식입니다: "no", "inline", "footnote".
pdf_preamble	문자열	""	생성한 문서 앞부분에 삽입할 원시 Typst 소스입니다.
pdf_font_paths	배열	[]	사용자 OTF/TTF 글꼴을 검색할 추가 디렉터리입니다.
pdf_packages	문자열	"download"	패키지 해석 정책입니다: "download" 또는 "offline".
typst	문자열	"typst"	시스템 Typst CLI의 이름 또는 절대 경로입니다.

PDF 책 정의

[[pdf_documents]] 테이블로 프로젝트에서 만들 책을 하나 이상 정의합니다.

[[pdf_documents]]
root = "index"
file = "guide.pdf"
title = "Field Notes Complete Guide"
author = "Author Name"

[[pdf_documents]]
root = "reference/index"
file = "reference.pdf"
title = "Field Notes Reference"
author = "Author Name"

MyST Markdown 옵션

표 14 MyST Markdown 옵션

키	형식	기본값	설명
myst_enable_extensions	배열	["dollarmath"]	구문 확장입니다: "colon_fence", "deflist", "dollarmath", "fieldlist", "tasklist", "substitution".
myst_heading_anchors	정수	0	제목 앵커를 자동 생성할 깊이입니다. 0 이면 비활성화합니다.
myst_substitutions	테이블	{}	Markdown 문서에서 사용할 변수 치환입니다: {key = "value"}.
myst_url_schemes	배열	["http", ...]	외부 링크로 인식할 URI 스킴입니다.
myst_commonmark_only	불리언	false	MyST 확장 없이 CommonMark 구문만 사용합니다.

Intersphinx 옵션

extensions = ["sphinx.ext.intersphinx"]
intersphinx_cache_limit = 5
intersphinx_timeout = 30

[intersphinx_mapping]
python = ["https://docs.python.org/3/", ""]
click = ["https://click.palletsprojects.com/", ["click.inv", ""]]

전체 절차는 다른 프로젝트로 연결 를 참고하세요.

Python autodoc 옵션

표 15 Autodoc 옵션

키	형식	기본값	설명
autodoc_source_paths	배열	[]	정적 분석에서 Python 모듈을 검색할 디렉터리입니다.
autoclass_content	문자열	"class"	클래스 docstring을 가져올 위치입니다: "class", "init", "both".
autodoc_member_order	문자열	"alphabetical"	멤버 정렬 방식입니다: "alphabetical", "bysource", "groupwise".
autodoc_typehints	문자열	"signature"	타입 힌트 위치입니다: "signature", "description", "none".
autodoc_default_options	테이블	{}	모든 auto* 지시문에 적용할 기본 옵션입니다.

전체 검색 규칙은 autodoc으로 Python 문서 작성하기 을 참고하세요.

Odin API 문서 옵션

표 16 Odin 도메인 옵션

키	형식	기본값	설명
odin_autoapi_dirs	배열	[]	Odin 패키지를 검색할 소스 디렉터리입니다.
odin_autoapi_root	문자열	"api"	생성할 Odin API 문서의 하위 디렉터리입니다.
odin_autoapi_options	배열	["members", "undoc-members"]	포함할 멤버를 거르는 필터입니다.
odin_autoapi_member_order	문자열	"source"	멤버 정렬 방식입니다: "source" 또는 "alphabetical".

Odin 도메인의 전체 사용법은 Odin 문서화 을 참고하세요.

국제화 옵션

표 17 i18n 옵션

키	형식	기본값	설명
locale_dirs	배열	["locales"]	gettext 카탈로그를 검색할 디렉터리입니다.
gettext_compact	불리언	true	같은 디렉터리의 문서 메시지를 하나의 카탈로그로 합칩니다.
gettext_uuid	불리언	false	POT 메시지에 안정적인 UUID를 기록합니다.
gettext_auto_build	불리언	true	빌드할 때 .po 를 바이너리 .mo 카탈로그로 컴파일합니다.
figure_language_filename	문자열	"{root}.{language}{ext}"	언어별 이미지를 선택할 파일 이름 템플릿입니다.

번역 절차는 국제화 을 참고하세요.