typo3-docs

TYPO3 Documentation スキル

docs.typo3.org の規約に従って、TYPO3 拡張機能のドキュメントを作成・保守します。

基本的なワークフロー

0. まだ Documentation/ がありませんか？ ファイルを手書きせず、次を実行してください。名前空間は、記憶を頼りに書くと間違いやすい部分です。guides.phpdoc.org と guides.typo3.org は、どちらも誰も提供していないアドレスです。名前空間を間違えたファイルは、整形式の XML でも何もレンダリングされません。

   mkdir -p Documentation && cat > Documentation/guides.xml <<'XML'
   <?xml version="1.0" encoding="UTF-8"?>
   <guides xmlns="https://www.phpdoc.org/guides" links-are-relative="true">
       <project title="TITLE" version="MAJOR.MINOR" release="MAJOR.MINOR.PATCH"/>
   </guides>
   XML
   grep -Fc 'xmlns="https://www.phpdoc.org/guides"' Documentation/guides.xml
   

   Settings.cfg は guides.xml に置き換えられたファイルです。もう読み込まれないため、作成しても拡張機能のドキュメントはレンダリングされず、エラーも表示されません。

   grep の出力は、名前空間が正しければ 1、正しくなければ 0 です。その後、TITLE と両方のバージョンを置き換えてください。<project> はそれらを属性として保持します。拡張キーをテキストにした要素にはタイトルもリリースもありません。assets/guides.xml.dist には拡張機能要素、相互リンク、ビルド設定を含むファイル全体があるため、このスキルのディレクトリにアクセスできる場合は、こちらを出発点にするのが適切です。

1. まず抽出を実行して不足箇所を見つけます。

   scripts/extract-all.sh /path/to/extension
   scripts/analyze-docs.sh /path/to/extension
   

2. 該当するリファレンスを確認します

3. 通常のテキストではなく、TYPO3 ディレクティブを使用します

4. 検証します：scripts/validate_docs.sh /path/to/extension

5. レンダリングします：scripts/render_docs.sh /path/to/extension

重要：「ドキュメントを表示」する場合は、生の RST ではなく HTML をレンダリングしてください。

要素の選択ガイド

コンテンツの種類	ディレクティブ
完全なコード	literalinclude（推奨）
短いコードスニペット	:caption: を指定した code-block
設定オプション	:type:、:default: を指定した confval
PHP API	php:method:: — nullable／union 型には :returntype:
注意事項	note、tip、warning、important
機能グリッド	フッターに stretched-link を指定した card-grid
選択肢	同期された tabs
スクリーンショット	:zoom: lightbox と境界線／影のクラスを指定した figure

重要なルール

公式ドキュメントを正とします。内容が矛盾する場合は、公開中のマニュアルを優先し、相違点を報告してください（references/canonical-sources.md）。

上流：

• UTF-8、4 スペースのインデント（タブなし）、LF。可能な限り 80 文字で折り返します
• ファイル名は CamelCase、見出しは 文の先頭のみ大文字
• すべての見出しの前に パーマリンクアンカー（.. _label:）
• すべてのサブディレクトリに Index.rst
• :alt: を指定した PNG/AVIF 画像
• PHP ドメイン：php:method:: で ?Type／Type|null を使用せず、:returntype: を使用します

NR の方針：mailto: は使用しません（上流では許可されていますが、スパム／個人情報のリスクがあるため、Issues／Discussions を使用します）。Documentation/ に .editorconfig を配置します。

目安：RST ファイルは 約 250 行。toctree で分割します。役立つ場合（バックエンドモジュール、設定、ワークフローなど）はスクリーンショットを追加します。

コード例の検証

コード例をソースと照合します。Classes/ でメソッド名を grep し、CLI 引数を configure() と比較します。 references/extraction-patterns.md を参照してください。

コミット前のチェックリスト

1. コードブロックに :caption: があり、インラインコードで適切なロールを使用している
2. スクリーンショットが存在し、:alt: と :zoom: lightbox が指定されている
3. scripts/validate_docs.sh が成功し、レンダリングに警告がない
4. README と Documentation/ の内容が同期している

参照資料

• references/canonical-sources.md -- トピックと上流ソースの対応表、出典ラベル
• references/file-structure.md -- レイアウト、命名規則
• references/guides-xml.md -- guides.xml のひな形、ビルド設定、相互リンク
• references/coding-guidelines.md -- CGL との差分、.editorconfig
• references/rst-syntax.md -- 見出し、句読点の注意点
• references/text-roles-inline-code.md -- :php:, :guilabel:, :ref:
• references/code-structure-elements.md -- コードブロック、confval、PHP ドメイン
• references/typo3-directives.md -- confval、versionadded、deprecated
• references/content-directives.md -- アコーディオン、タブ、カードグリッド
• references/screenshots.md -- 図、画像のルール、SVG 図
• references/rendering.md -- Docker コマンド、ライブプレビュー
• references/intercept-deployment.md -- Webhook、ビルドトリガー
• references/asset-templates-guide.md -- テンプレート、スクリーンショットのワークフロー
• references/architecture-decision-records.md -- ADR のパターン
• references/documentation-coverage-analysis.md -- カバレッジの評価
• references/scripts-guide.md -- スクリプトのオプション
• references/typo3-extension-architecture.md -- 拡張機能のレイアウト
• references/upstream-docs-contribution.md -- 上流ドキュメントへの PR
• references/render-guides-development.md -- レンダラー自体の変更：ディレクティブのオプション、相互リンクの解析、統合フィクスチャのセマンティクス