Menggunakan SPHINX untuk dokumentasi projek PHP

dengan cekap menulis dokumentasi projek PHP: Panduan Sphinx dan Readthedocs

Artikel ini akan membimbing anda cara menggunakan Sphinx dan Readthedocs untuk membuat dokumen projek PHP berkualiti tinggi, yang meliputi langkah-langkah utama seperti pemasangan, penyesuaian tema, penonjolan sintaks PHP, penyebaran readthedocs, dll.

mata teras:

• Pemasangan SPHINX diintegrasikan dengan ReadThedocs: Gunakan SPHINX untuk menggabungkan readthedocs, format REST dan markdown dengan mudah untuk membuat dokumen projek PHP profesional.
• Struktur folder yang disyorkan: Untuk mengoptimumkan organisasi projek, disarankan untuk meletakkan dokumen dan kod projek dalam folder yang sama, atau membuat repositori kod bebas berdasarkan saiz projek.
• Tema Custom: Meningkatkan estetika dokumen dan meningkatkan pengalaman pengguna melalui pemasangan dan konfigurasi. sphinx_rtd_theme
• PHP sintaks penonjolan dan konfigurasi domain: Pasang sambungan untuk melaksanakan sintaks kod PHP dan sokongan bahasa PHP yang lebih tepat untuk meningkatkan kebolehbacaan kod. sphinxcontrib-phpdomain
• Penyebaran dan lanjutan ReadThedocs: Menyebarkan dokumen ke readthedocs untuk akses dan pengurusan yang mudah, dan menggunakan peningkatan lanjutan.

Readthedocs adalah platform hosting dokumen yang digunakan secara meluas dalam industri. Ia menyokong binaan tempatan dan hosting dalam talian, menjadikannya lebih mudah bagi pemaju untuk mengawal versi dan kerjasama pasukan.

Permulaan cepat:

Perintah berikut dapat dengan cepat membina persekitaran dokumen Sphinx:

Dayakan tema dan sintaks PHP yang menonjol setelah menyelesaikan permulaan cepat:

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

membina dokumen 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

atau

make html

sphinx-build -b html source build

pemasangan sphinx:

Readthedocs menggunakan sphinx dalam lapisan asas, jadi sphinx dan kebergantungannya perlu dipasang. Gunakan untuk memasang alat yang diperlukan.

Struktur folder yang disyorkan: pip install sphinx sphinx-autobuild

Dokumen boleh diletakkan dalam folder yang sama seperti kod projek, atau dalam repositori kod berasingan. Adalah disyorkan bahawa projek kecil meletakkan dokumen dalam folder projek, seperti . Gunakan fail untuk mudah mengecualikan dokumen dari siaran projek.

my-php-project/docs Tema Custom: .gitattributes

Gunakan Memasang tema dan konfigurasikannya dalam fail

:

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

Struktur direktori:

Dalam proses

, anda perlu menentukan nama fail dokumen utama (biasanya ). Dokumen utama menggunakan arahan untuk menghasilkan direktori:

sphinx-quickstart index.rst

PHP sintaks PHP:

tambahkan kod berikut ke

fail untuk membolehkan sintaks PHP menyoroti: 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 Field:

Pasang

Sokongan bahasa PHP yang dipertingkatkan:

dan membolehkan: sphinxcontrib-phpdomain dalam sudo pip install sphinxcontrib-phpdomain. conf.py extensions = ["sphinxcontrib.phpdomain"]

Lihat Kod Sumber:

tambahkan kod berikut dalam

untuk memaparkan pautan kod sumber github dalam dokumen:

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

rehat dan markdown:

Sphinx menyokong rehat dan markdown. Pasang pelanjutan untuk menyokong markdown:

dan konfigurasikan dalam

: recommonmark sudo pip install recommonmark conf.py

Readthedocs Deployment:

make html

Buat projek baru di Readthedocs, sambungkan repositori GitHub anda untuk membina dan menggunakan dokumen secara automatik.

extension readthedocs:

Buat fail untuk menyenaraikan kebergantungan dan tentukan laluan fail dalam tetapan projek ReadThedocs.

FAQs: requirements.txt

(bahagian Soalan Lazim dalam dokumen asal ditinggalkan di sini kerana artikel itu terlalu panjang dan kandungannya diduplikasi atau terlalu asas dari kandungan yang ada. Jika perlu, anda boleh bertanya soalan FAQ secara berasingan.)

Ringkasan:

Artikel ini memperkenalkan proses lengkap untuk membuat dokumen projek PHP menggunakan Sphinx dan Readthedocs. Dengan konfigurasi dan penyesuaian tema yang munasabah, anda boleh membuat dokumen yang indah, mudah-untuk-usul dan mudah diakses yang meningkatkan profesionalisme dan mengekalkan projek anda.

Atas ialah kandungan terperinci Menggunakan SPHINX untuk dokumentasi projek PHP. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!