Guidedog / 문서 0.2.0

도메인¶

도메인은 특정 프로그래밍 언어나 분야의 객체를 설명하고 상호 참조하는 지시문과 역할의 모음입니다.

Guidedog에는 다음 Sphinx 도메인이 기본 구현되어 있습니다.

표준 도메인 (std): 명령줄 옵션, 환경 변수, 용어, UI 레이블 등 일반 문서 객체입니다.
Python 도메인 (py): 모듈, 클래스, 함수, 메서드, 속성, 프로퍼티, 예외입니다.
C 도메인 (c): 함수, 타입, 구조체, 공용체, 열거형, 열거자, 변수, 매크로입니다.
C++ 도메인 (cpp): 클래스, 콘셉트, 템플릿, 네임스페이스, 메서드, 표현식입니다.
JavaScript 도메인 (js): 함수, 메서드, 클래스, 프로퍼티입니다.
Odin 도메인 (odin): Odin 패키지, 프로시저, 구조체, 공용체, 열거형입니다. Odin 문서화 을 참고하세요.

기본 도메인 설정¶

conf.toml 의 primary_domain 으로 기본 도메인을 설정합니다. 기본값은 "py" 입니다. 설정하면 접두사를 생략할 수 있습니다. 예를 들어 .. py:function:: 대신 .. function:: 을, :py:func:`name` 대신 :func:`name` 을 쓸 수 있습니다.

문서 안에서 현재 도메인을 바꾸려면 다음과 같이 작성합니다.

.. default-domain:: c

표준 도메인¶

표준 도메인은 명령줄 도구, 환경 변수, 문서 상호 참조를 설명합니다.

지시문¶

.. program:: mytool

.. option:: -c <config>, --config <config>

   Path to the configuration file.

.. envvar:: GUIDEDOG_THEME

   Specifies the default theme stylesheet.

역할¶

:doc:`path`: 상대 경로로 프로젝트 문서에 연결합니다.
:ref:`label`: 명시적 대상 레이블 .. _label: 에 연결합니다.
:term:`term`: glossary 에 정의한 용어에 연결합니다.
:option:`--config`: option 에 설명한 명령줄 옵션에 연결합니다.
:envvar:`VARIABLE`: envvar 에 설명한 환경 변수에 연결합니다.
:command:`name`: 시스템 명령 이름을 표시합니다.
:file:`path`: 파일이나 디렉터리 경로를 표시합니다. {variable} 자리표시자도 지원합니다.
:kbd:`Ctrl+C`: 키보드 입력을 표시합니다.
:menuselection:`File --> Save As`: 메뉴 선택 순서를 표시합니다.
:guilabel:`Submit`: 버튼이나 UI 요소를 표시합니다.
:pep:`8`: Python 개선 제안에 연결합니다.
:rfc:`7231`: IETF RFC 문서에 연결합니다.

Python 도메인¶

Python 도메인은 Python 인터페이스와 시그니처를 설명합니다.

지시문¶

.. py:module:: pipeline.reader
   :synopsis: Document reading and normalization.

.. py:class:: DocumentReader(source_path: str, encoding: str = "utf-8")

   Base class for document readers.

   .. py:method:: parse(content: bytes) -> Document

      Parses raw bytes into a document tree.

      :param content: Raw source content bytes.
      :return: Parsed document tree instance.
      :raises ValueError: If the source format is unrecognized.

   .. py:attribute:: encoding
      :type: str

      The character encoding used for text decoding.

지원하는 지시문은 py:module, py:currentmodule, py:function, py:data, py:class, py:method, py:staticmethod, py:classmethod, py:attribute, py:property, py:exception, py:decorator, py:type 입니다.

역할¶

:py:func:`name`: Python 함수에 연결합니다.
:py:class:`name`: Python 클래스에 연결합니다.
:py:meth:`name`: Python 클래스 메서드 또는 인스턴스 메서드에 연결합니다.
:py:attr:`name`: Python 속성에 연결합니다.
:py:data:`name`: Python 모듈 수준 데이터에 연결합니다.
:py:exc:`name`: Python 예외 클래스에 연결합니다.
:py:mod:`name`: Python 모듈에 연결합니다.

C 도메인¶

C 도메인은 C 라이브러리와 헤더 파일을 설명합니다.

지시문¶

.. c:namespace:: gd

.. c:struct:: Workspace

   A contiguous memory buffer for in-memory document parsing.

   .. c:member:: size_t capacity

      Total byte size of the storage slab.

.. c:function:: int gd_convert(Workspace *ws, const char *input, char *output, size_t out_len)

   Converts source text into HTML.

   :param ws: Pointer to the initialized workspace.
   :param input: Null-terminated input string.
   :param output: Destination buffer.
   :param out_len: Size of destination buffer.
   :returns: 0 on success, or an error code.

역할¶

:c:func:`name`: C 함수에 연결합니다.
:c:member:`name`: C 구조체 또는 공용체 멤버에 연결합니다.
:c:data:`name` / :c:var:`name`: C 변수에 연결합니다.
:c:type:`name`: C typedef 또는 타입에 연결합니다.
:c:struct:`name`: C 구조체에 연결합니다.
:c:union:`name`: C 공용체에 연결합니다.
:c:enum:`name`: C 열거형에 연결합니다.
:c:macro:`name`: C 전처리기 매크로에 연결합니다.

C++ 도메인¶

C++ 도메인은 현대 C++ 구문, 콘셉트, 네임스페이스, 범위를 지원합니다.

지시문¶

.. cpp:namespace:: guidedog

.. cpp:concept:: template<typename T> Reader

   Specifies requirements for document reader types.

.. cpp:class:: template<typename Allocator> Builder

   Constructs AST document nodes.

   .. cpp:function:: NodeId add_text(std::string_view text)

      Appends text to the active node.

역할¶

:cpp:class:`name`: C++ 클래스 또는 구조체에 연결합니다.
:cpp:func:`name`: C++ 함수 또는 메서드에 연결합니다.
:cpp:member:`name` / :cpp:var:`name`: 멤버 또는 변수에 연결합니다.
:cpp:type:`name`: C++ 타입 별칭 또는 typedef에 연결합니다.
:cpp:concept:`name`: C++20 콘셉트에 연결합니다.
:cpp:enum:`name`: C++ 열거형에 연결합니다.

JavaScript 도메인¶

JavaScript 도메인은 브라우저 스크립트, 라이브러리, Node.js 모듈을 설명합니다.

지시문¶

.. js:module:: theme

.. js:class:: ThemeController(options)

   Manages color themes and local storage persistence.

   .. js:method:: toggleTheme()

      Toggles between light and dark modes.

역할¶

:js:func:`name`: JavaScript 함수에 연결합니다.
:js:meth:`name`: JavaScript 메서드에 연결합니다.
:js:class:`name`: JavaScript 클래스에 연결합니다.
:js:data:`name`: JavaScript 변수에 연결합니다.
:js:attr:`name`: JavaScript 객체 속성에 연결합니다.
:js:mod:`name`: JavaScript 모듈에 연결합니다.

상호 참조 규칙¶

도메인 상호 참조는 다음과 같은 수식 방법을 지원합니다.

접두사 숨기기: 대상 앞에 ~ 를 붙이면 이름의 마지막 부분만 표시합니다. :py:func:`~pipeline.reader.DocumentReader.parse` 는 parse() 로 표시됩니다.
현재 범위에서 검색: 상대 참조는 현재 모듈이나 네임스페이스를 먼저 찾고, 없으면 전체 범위에서 검색합니다.
정확한 일치: 대상 앞에 . 을 붙이면 현재 모듈이나 포함 객체부터 검색합니다.