Guidedog¶
한 번 쓰고, 잘 설명하고, 웹과 종이에 펴냅니다.
Guidedog는 같은 reStructuredText 또는 Markdown 파일로 문서 웹사이트와 PDF 책을 만듭니다. 글은 한 번만 쓰면 되고, 두 판의 내용은 Guidedog가 맞춰 줍니다.
일반 텍스트 파일을 넣으면 Guidedog가 그것으로 웹 페이지와 책 페이지를 만듭니다.
하는 일¶
- 웹사이트. 탐색, 검색, 코드 강조, 밝은 테마와 어두운 테마를 갖춘 페이지를, 마음대로 고칠 수 있는 Jinja 템플릿으로 만듭니다.
- PDF 책. 장, 상호 참조, 그림, 표, 각주, 색인을 언어마다 알맞은 규칙으로 Typst가 조판합니다.
- reStructuredText와 Markdown. 지시문, 역할, toctree, 상호 참조가 Sphinx 사용자가 아는 대로 동작하고, MyST Markdown을 함께 쓸 수도 있습니다.
- 번역. gettext 카탈로그로 프로젝트를 다른 언어로 옮깁니다. 중국어, 일본어, 한국어, 힌디어 글도 화면과 종이에서 바르게 배치됩니다.
- 도표, 수식, API 페이지. Graphviz 도표, LaTeX 수식, 소스 코드에서 읽은 Odin API 참조.
- 알기 쉬운 오류. 무엇이 잘못되었는지, 어디인지, 어떻게 고치는지를 메시지가 알려 줍니다. 빌드가 실패해도 마지막으로 성공한 사이트는 그대로 남습니다.
하나의 프로그램¶
Guidedog는 실행 파일 하나입니다. Python 환경도, LaTeX 설치도, 따로 설치하는 테마나 확장 패키지도 필요 없습니다. 설정은 TOML 파일 하나이고, 템플릿은 프로젝트 안에 있는 고칠 수 있는 평범한 파일입니다.
아직 바깥에서 가져오는 것도 있습니다. Guidedog는 Typst와 Graphviz를 안에 넣어 빌드할 수 있고, 넣지 않은 빌드는 시스템에 설치된 typst 와 Graphviz 프로그램을 씁니다. Linux와 macOS에서는 libcurl 같은 시스템 라이브러리도 몇 가지 씁니다.
한 번 쓰고, 둘 다 보기¶
왼쪽은 reStructuredText이고, 오른쪽은 Guidedog가 그것으로 이 페이지에 만든 결과입니다. PDF 빌더는 같은 내용을 책 페이지로 조판합니다.
.. note::
Guidedog는 글을 한 번만 읽습니다.
*같은* 파일이 **웹사이트** 도 되고
**책** 도 됩니다.
.. list-table::
:header-rows: 1
* - 빌더
- 결과
* - ``html``
- 웹사이트
* - ``pdf``
- PDF 책
같은 파일이 웹사이트 도 되고 책 도 됩니다.
| 빌더 | 결과 |
|---|---|
html |
웹사이트 |
pdf |
PDF 책 |
PDF 책으로 만든 설명서 가 종이에서의 결과를 보여 주는 예입니다. 설명서 웹사이트와 같은 파일로 만들었습니다.
시작하기¶
최신 릴리스 에서 시스템에 맞는 압축 파일을 내려받아 guidedog 를 PATH 에 두고, 프로젝트를 만듭니다.
guidedog quickstart docs
guidedog build html docs
guidedog build pdf docs
guidedog serve docs
quickstart 는 conf.toml, index.rst, 고칠 수 있는 템플릿을 만듭니다. serve 는 글을 쓰는 동안 사이트를 다시 빌드합니다. 튜토리얼 에서 첫 프로젝트를 차례로 따라 할 수 있습니다. Guidedog를 소스에서 빌드하려면 Odin을 설치하고 저장소의 안내 를 따르세요.
설계 논의¶
Guidedog의 설계 결정은 번호가 붙은 논의로 기록합니다. 문제, 대안, 결정, 근거를 담습니다. 각 논의는 웹에서 읽거나 PDF로 내려받을 수 있습니다.