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

この記事では、SphinxとReadthedocsを使用して高品質(zhì)のPHPプロジェクトドキュメントを作成する方法を?qū)Г蓼埂％ぅ螗攻醛`ル、テーマのカスタマイズ、PHP構(gòu)文の強調(diào)表示、Readthedocs展開などの重要な手順をカバーします。

コアポイント：

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

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

クイックスタート：

次のコマンドは、スフィンクスドキュメント環(huán)境をすばやく構(gòu)築できます：

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

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()]

# 設(shè)置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は基礎(chǔ)となる層でスフィンクスを使用するため、スフィンクスとその依存関係をインストールする必要があります。 必要なツールをインストールするには、

を使用してください。

pip install sphinx sphinx-autobuild

推奨フォルダー構(gòu)造：

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

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

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

カスタムテーマ：

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

ファイルに構(gòu)成します：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()]

ディレクトリ構(gòu)造：

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

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

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

php構(gòu)文強調(diào)表示：

次のコードを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()]

# 設(shè)置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で構(gòu)成 sudo pip install recommonmark conf.py

readthedocs deployment：

make html

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

readthedocs拡張子：

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

requirements.txtfaqs：

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

概要：

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

以上がPHPプロジェクトのドキュメントにSphinxを使用しますの詳細(xì)內(nèi)容です。詳細(xì)については、PHP 中國語 Web サイトの他の関連記事を參照してください。