PHPプロジェクトのドキュメントにSphinxを使用します

効率的にPHPプロジェクトのドキュメントを書く：Sphinx and Readthocs Guide

この記事では、SphinxとReadthedocsを使用して高品質のPHPプロジェクトドキュメントを作成する方法を導きます。インストール、テーマのカスタマイズ、PHP構文の強調表示、Readthedocs展開などの重要な手順をカバーします。

コアポイント：

• sphinxのインストールは、readthedocsと統合されています： sphinxを使用してreadthedocsを組み合わせ、レストとマークダウン形式をサポートして、プロのPHPプロジェクトドキュメントを簡単に作成します。
• 推奨フォルダー構造：プロジェクト組織を最適化するには、ドキュメントとプロジェクトコードを同じフォルダーに配置するか、プロジェクトのサイズに基づいて独立したコードリポジトリを作成することをお勧めします。
• カスタムテーマ：ドキュメントの美学を改善し、インストールと構成を通じてユーザーエクスペリエンスを強化します。 sphinx_rtd_theme
PHP構文の強調表示とドメイン構成：
• インストールextension PHPコード構文強調表示とより正確なPHP言語サポートを実装して、コードの読みやすさを改善します。 sphinxcontrib-phpdomain
readthedocsの展開と拡張機能：
• アクセスと管理のためにドキュメントをreadthedocsに展開し、拡張機能を活用します。

readthedocsは、業界で広く使用されているドキュメントホスティングプラットフォームです。これは、技術文書の執筆に特に適した2つのマークアップ言語です。ローカルビルドとオンラインホスティングをサポートしているため、開発者がバージョン制御とチームコラボレーションを容易にします。

クイックスタート：

次のコマンドは、スフィンクスドキュメント環境をすばやく構築できます：

クイックスタートアップを完了した後にテーマとPHPの構文の強調表示を有効にします：

sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinxcontrib-phpdomain
mkdir docs
cd docs
sphinx-quickstart
wget https://gist.githubusercontent.com/Swader/b16b18d50b8224f83d74/raw/b3c1d6912aefc390da905c8b2bb3660f513af713/requirements.txt

htmlドキュメントをビルド：

sed -i '/extensions = \[\]/ c\extensions = \["sphinxcontrib.phpdomain"\]' source/conf.py
echo '

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# 设置PHP语法高亮
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
lexers["php"] = PhpLexer(startinline=True, linenos=1)
lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1)
primary_domain = "php"

' >> source/conf.py

または

make html

sphinx-build -b html source build

sphinxのインストール：

readthedocsは基礎となる層でスフィンクスを使用するため、スフィンクスとその依存関係をインストールする必要があります。 必要なツールをインストールするには、

を使用してください。

pip install sphinx sphinx-autobuild

推奨フォルダー構造：

ドキュメントは、プロジェクトコードと同じフォルダー、または別のコードリポジトリに配置できます。 小規模プロジェクトは、

などのプロジェクトフォルダーにドキュメントを配置することをお勧めします。

ファイルを使用して、プロジェクトリリースからドキュメントを簡単に除外します。 my-php-project/docs .gitattributes

カスタムテーマ：

テーマをインストールし、

ファイルに構成します：pip install sphinx_rtd_theme sphinx_rtd_theme source/conf.py

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

ディレクトリ構造：

プロセスでは、メインのドキュメントファイル名（通常は

）を指定する必要があります。 メインドキュメントは、

コマンドを使用してディレクトリを生成します。 sphinx-quickstart index.rst toctree

php構文強調表示：

次のコードをsource/conf.py

sudo pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinxcontrib-phpdomain
mkdir docs
cd docs
sphinx-quickstart
wget https://gist.githubusercontent.com/Swader/b16b18d50b8224f83d74/raw/b3c1d6912aefc390da905c8b2bb3660f513af713/requirements.txt

phpフィールド：

インストール

拡張拡張PHP言語サポート：

およびenable：sphinxcontrib-phpdomaininsudo pip install sphinxcontrib-phpdomain。 conf.py extensions = ["sphinxcontrib.phpdomain"]

ソースコードの表示：

次のコードを

に追加して、ドキュメントにgithubソースコードリンクを表示します。

conf.py

sed -i '/extensions = \[\]/ c\extensions = \["sphinxcontrib.phpdomain"\]' source/conf.py
echo '

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# 设置PHP语法高亮
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
lexers["php"] = PhpLexer(startinline=True, linenos=1)
lexers["php-annotations"] = PhpLexer(startinline=True, linenos=1)
primary_domain = "php"

' >> source/conf.py

休息とマークダウン：

SphinxはRest and Markdownをサポートしています。 マークダウンをサポートするために拡張機能をインストール：

：

：recommonmarkで構成 sudo pip install recommonmark conf.py

readthedocs deployment：

make html

readthedocsで新しいプロジェクトを作成し、githubリポジトリを接続してドキュメントを自動的に構築および展開します。

readthedocs拡張子：

依存関係をリストし、readthedocsプロジェクトの設定でファイルパスを指定するファイルを作成します。

requirements.txtfaqs：

（元のドキュメントのFAQパーツは、記事が長すぎてコンテンツが複製されているか、既存のコンテンツから基本的すぎるため、ここで省略されています。必要に応じて、FAQの質問を個別に尋ねることができます。）

概要：

この記事では、SphinxとReadthedocsを使用してPHPプロジェクトドキュメントを作成する完全なプロセスを紹介します。 合理的な構成とテーマのカスタマイズを使用すると、プロジェクトのプロフェッショナリズムと保守性を向上させる美しく、維持しやすく、アクセスしやすいドキュメントを作成できます。

以上がPHPプロジェクトのドキュメントにSphinxを使用しますの詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。