このページの内容

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 Enhancement Proposal にリンクします。
• :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() になります。
• 現在のスコープ : 相対参照は、まず現在のモジュールや名前空間を調べ、その後で全体を検索します。
• 完全一致 : . を付けると、現在のモジュールや包含するオブジェクトから検索します。