Guidedog / 문서 0.2.0

문서 작성¶

Guidedog은 reStructuredText (.rst)와 MyST Markdown (.md)을 지원합니다. 두 형식을 공통 문서 트리로 파싱해 HTML 사이트와 PDF 책을 생성합니다.

소스 언어 선택¶

도메인, 복잡한 표, 확장 가능한 지시문이 필요하면 reStructuredText를 사용하세요. Markdown 구문과 Sphinx 스타일의 지시문 및 역할을 함께 쓰려면 MyST Markdown을 선택하세요.

프로젝트의 Markdown 문서는 MyST로 파싱합니다. 단일 파일을 변환하는 guidedog convert 는 MyST를 명시하지 않으면 CommonMark를 사용합니다.

제목과 구조¶

문서 제목은 페이지를 식별하고 절과 하위 절은 내용을 나눕니다. RST 제목에는 밑줄을 쓰며 같은 윗줄도 추가할 수 있습니다. 줄 길이는 제목보다 짧으면 안 됩니다.

권장하는 제목 기호:

Document Title
==============

Section Heading
---------------

Subsection
~~~~~~~~~~

Sub-subsection
^^^^^^^^^^^^^^

Paragraph Heading
"""""""""""""""""

프로젝트 전체에서 제목 수준을 일관되게 유지하세요. MyST Markdown에서는 #, ##, ### 를 사용합니다.

텍스트 형식과 인라인 마크업¶

인라인 마크업은 장식보다 의미를 전달하는 데 사용하세요.

표 1 인라인 마크업¶
스타일	reStructuredText	MyST Markdown
굵게	`strong text`	`strong text`
강조 / 기울임	`emphasized text`	`emphasized text`
`인라인 코드`	``inline code``	`inline code`
아래 첨자	:sub:`text`	{sub}`text`
위 첨자	:sup:`text`	{sup}`text`

별표나 백틱을 문자 그대로 쓰려면 \*not italic\* 처럼 백슬래시로 이스케이프하세요.

목록¶

Guidedog은 네 종류의 목록을 지원합니다.

글머리 기호 목록¶

* First item
* Second item with multiple lines
  of continuing explanation.
* Third item

번호 목록¶

1. Numbered item
2. Second item
#. Automatically numbered item
#. Next auto-numbered item

정의 목록¶

정의 목록은 용어와 설명을 짝으로 묶습니다. 용어를 한 줄에 쓰고 바로 다음 줄부터 들여쓴 정의를 적습니다.

Workspace
   A bounded memory buffer supplied by the caller for document conversion.

Session
   A host-level coordinator that manages memory budgets and document caches.

필드 목록¶

필드 목록은 구조화된 메타데이터와 매개변수 설명에 사용합니다.

:Authors: Jane Doe, John Smith
:Version: 1.2
:Status: Active

코드 블록¶

code-block 또는 sourcecode 로 구문을 강조한 코드를 표시하세요. Guidedog은 35개 이상의 프로그래밍 언어를 지원합니다.

.. code-block:: python
   :linenos:
   :caption: Server entry point
   :emphasize-lines: 2, 4-5

   def main():
       app = create_app()
       app.run(host="0.0.0.0", port=8080)

코드 블록 옵션:

:linenos:: 코드 옆에 줄 번호를 표시합니다.
:caption: Title: 코드 위나 아래에 캡션을 붙입니다.
:emphasize-lines: 1, 3-5: 지정한 줄을 강조합니다.
:name: label: 코드 블록에 참조 대상을 지정합니다.

외부 소스 파일을 직접 포함하려면 literalinclude 를 사용하세요.

.. literalinclude:: ../src/server.py
   :language: python
   :lines: 1-25
   :linenos:

안내 상자¶

안내 상자는 주의 사항, 경고, 보충 설명을 강조합니다.

.. note::
   Helpful background context or implementation detail.

.. tip::
   Suggested best practices or workflow shortcuts.

.. important::
   Essential requirements that must not be overlooked.

.. warning::
   Conditions that could lead to unexpected behavior or lost work.

.. caution::
   Potential pitfalls or sensitive operational steps.

.. seealso::
   References to related chapters, specifications, or external guides.

Guidedog은 danger, error, hint, attention 도 지원합니다. 제목을 직접 지정하려면 admonition 을 사용하세요.

.. admonition:: Design Rationale

   Explains why a particular architecture was chosen.

표¶

Guidedog은 단순 표, 격자 표, 지시문 기반 표를 지원합니다.

단순 표¶

단순 표는 가로선으로 열의 범위를 표시합니다.

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
True   True   True
=====  =====  =======

격자 표¶

격자 표는 여러 줄의 셀과 행·열 병합을 지원합니다.

+------------------------+------------+----------+
| Header row, column 1   | Column 2   | Column 3 |
+========================+============+==========+
| Cell with multiple     | Second     | Third    |
| paragraphs of text.    | column     | column   |
+------------------------+------------+----------+

목록 표¶

list-table 은 중첩 글머리 기호 목록으로 표를 만듭니다. 넓은 표도 소스에서 읽고 관리하기 쉽습니다.

.. list-table:: Project configurations
   :widths: 25 25 50
   :header-rows: 1

   * - Target
     - Builder
     - Description
   * - Website
     - ``html``
     - Static HTML documentation site
   * - Book
     - ``pdf``
     - Typeset PDF book powered by Typst

CSV 표¶

csv-table 은 쉼표로 구분한 값으로 표를 만듭니다.

.. csv-table:: Comparative metrics
   :header: "Name", "Time (ms)", "Memory (MB)"
   :widths: 40, 30, 30

   "Cold build", 42, 12
   "Incremental", 3, 4

이미지와 그림¶

image 와 figure 로 이미지, 스크린샷, 도표를 넣습니다.

.. image:: /assets/architecture.png
   :width: 600px
   :align: center
   :alt: System architecture diagram

.. figure:: /assets/flow.png
   :scale: 80%
   :align: center
   :alt: Execution flowchart

   Data flows sequentially through reader, resolver, and renderer.

figure 는 이미지에 캡션을 붙이며 참조 대상도 지정할 수 있습니다.

목차 트리로 문서 구성¶

toctree 는 문서 계층, 탐색 메뉴, HTML과 PDF의 읽는 순서를 정의합니다.

.. toctree::
   :maxdepth: 2
   :caption: User Guide
   :numbered:

   installation
   quickstart
   configuration

toctree 의 주요 옵션:

:maxdepth: N: 목차에 포함할 제목 깊이입니다.
:caption: Title: 탐색 항목 위에 표시할 범주 제목입니다.
:numbered:: 장과 제목에 번호를 붙입니다.
:titlesonly:: 문서 제목만 표시하고 내부 절은 생략합니다.
:hidden:: 본문에 목록을 표시하지 않고 문서의 읽는 순서만 기록합니다.
:glob:: tutorials/* 같은 와일드카드로 문서를 선택할 수 있습니다.

상호 참조와 링크¶

명시적 대상 레이블은 문서 파일 이름과 별개로 안정적인 참조를 제공합니다.

대상 레이블과 `:ref:`¶

제목, 표, 그림 바로 앞에 대상 레이블을 놓습니다.

.. _storage-model:

Storage model
-------------

Caller storage is bounded and measured upfront.

프로젝트의 어느 문서에서든 이 대상을 참조할 수 있습니다.

See :ref:`storage-model` for details.
See :ref:`custom link text <storage-model>`.

`:doc:` 문서 참조¶

확장자를 생략한 경로로 다른 문서에 연결합니다.

Read the :doc:`configuration guide <../reference/configuration>` for details.

`:term:` 용어 참조¶

glossary 로 용어를 정의합니다.

.. glossary::

   Workspace
      A fixed memory arena allocated by the caller for conversion passes.

   Pass
      An in-memory transformation step operating on the document AST.

:term: 역할로 용어에 연결합니다.

Conversion runs within an allocated :term:`workspace`.

`:download:` 파일 다운로드¶

파일을 다운로드 디렉터리로 복사하고 링크를 만듭니다.

Download the :download:`starter template <files/starter.toml>`.

외부 링크¶

외부 웹 주소에 연결합니다.

Visit `Typst <https://typst.app>`_ for typography details.

치환과 포함¶

재사용할 문구, 기호, 이미지를 정의합니다.

.. |version| replace:: 1.0.0
.. |brand| replace:: **Field Notes**

Welcome to |brand| version |version|.

여러 파일에서 reStructuredText 내용을 공유하려면 다음과 같이 작성합니다.

.. include:: ../shared/warnings.rst

MyST Markdown 작성¶

MyST Markdown은 펜스 블록으로 같은 지시문과 역할의 의미를 표현합니다.

# Project overview

Here is a paragraph with **bold text**, *italic emphasis*, and `inline code`.

```{note}
This note is rendered identically to a reStructuredText note directive.
```

```{code-block} python
:caption: Example function
:linenos:

def add(a, b):
    return a + b
```

```{toctree}
:maxdepth: 2
:caption: Navigation

first-chapter
second-chapter
```

See {ref}`storage-model` or consult the {doc}`../reference/configuration`.