Verwenden von Sphinx für PHP -Projektdokumentation

effizient Schreiben Sie PHP -Projektdokumentation: Sphinx und Redethedocs Guide

In diesem Artikel werden Sie mit Sphinx und Redethedocs geführt, um qualitativ hochwertige PHP-Projektdokumente zu erstellen und wichtige Schritte wie Installation, Themenanpassung, PHP-Syntax-Hervorhebung, Redethedocs-Bereitstellung usw. abzudecken.

Kernpunkte:

• Sphinx -Installation integriert sich in Redethedocs: Verwenden Sie Sphinx, um RededheDocs zu kombinieren, Ruhe- und Markdown -Formate zu unterstützen, um professionelle PHP -Projektdokumente problemlos zu erstellen.
• Empfohlene Ordnerstruktur: Um die Projektorganisation zu optimieren, wird empfohlen, die Dokumente und den Projektcode im selben Ordner zu platzieren oder ein unabhängiges Code -Repository basierend auf der Projektgröße zu erstellen.
• Benutzerdefiniertes Thema: Verbesserung der Ästhetik von Dokumenten und Verbesserung der Benutzererfahrung durch Installation und Konfiguration. sphinx_rtd_theme
• PHP -Syntax -Hervorhebung und Domänenkonfiguration: Erweiterung Umgang mit der Hervorhebung der PHP -Code -Syntax und einer genaueren Unterstützung der PHP -Sprache zur Verbesserung der Code -Lesbarkeit. sphinxcontrib-phpdomain
• Redethedocs Bereitstellung und Erweiterung: Dokumente für den einfachen Zugriff und die Verwaltung von Dokumenten bereitstellen und Erweiterungsverbesserungen verwenden.

RededheDocs ist eine weit verbreitete Dokument -Hosting -Plattform in der Branche. Es unterstützt lokale Build- und Online -Hosting, wodurch es Entwicklern für die Versionskontrolle und die Zusammenarbeit von Teams erleichtert wird.

Schneller Start:

Die folgenden Befehle können schnell die Sphinx -Dokumentumgebung erstellen:

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

themen- und pHP -Syntax -Hervorhebung nach Abschluss des schnellen Starts:

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

HTML -Dokument erstellen:

make html

oder

sphinx-build -b html source build

sphinx Installation:

rededheDocs verwendet Sphinx in der zugrunde liegenden Schicht, sodass Sphinx und seine Abhängigkeiten installiert werden müssen. Verwenden Sie

, um die erforderlichen Werkzeuge zu installieren. pip install sphinx sphinx-autobuild

Empfohlene Ordnerstruktur:

Dokumente können in denselben Ordner wie der Projektcode oder in einem separaten Code -Repository platziert werden. Es wird empfohlen, dass kleine Projekte Dokumente in Projektordnern wie

platzieren. Verwenden Sie my-php-project/docs Dateien, um Dokumente von Projektveröffentlichungen einfach auszuschließen. .gitattributes

benutzerdefiniertes Thema:

Verwenden Sie

das Thema pip install sphinx_rtd_theme und konfigurieren Sie es in der Datei 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()]

Verzeichnisstruktur:

im Prozess

müssen Sie den Namen der Hauptdokumentdatei angeben (normalerweise sphinx-quickstart). Das Hauptdokument verwendet den Befehl index.rst, um das Verzeichnis zu generieren: toctree

.. toctree::
   :maxdepth: 2

   overview
   quickstart

PHP -Syntax -Hervorhebung:

Fügen Sie den folgenden Code der Datei source/conf.py hinzu, um die PHP -Syntax -Hervorhebung zu aktivieren:

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 -Feld:

Installieren Sie sphinxcontrib-phpdomain erweitert erweiterte PHP -Sprachunterstützung: sudo pip install sphinxcontrib-phpdomain und aktivieren Sie: conf.py in extensions = ["sphinxcontrib.phpdomain"].

Quellcode anzeigen:

Fügen Sie den folgenden Code in conf.py hinzu, um den Link zum GitHub -Quellcode im Dokument anzuzeigen:

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

REST UND MARKDOWN:

sphinx unterstützt Ruhe und Markdown. Installieren Sie die Erweiterung recommonmark, um Markdown zu unterstützen: sudo pip install recommonmark und konfigurieren Sie in conf.py:

make html

redethedocs Bereitstellung:

Erstellen Sie ein neues Projekt auf RededheDocs und verbinden Sie Ihr Github -Repository, um Dokumente automatisch zu erstellen und bereitzustellen.

redeTHEDOCS -Erweiterung:

Erstellen Sie eine requirements.txt Datei, um Abhängigkeiten aufzulisten, und geben Sie den Dateipfad in den Redethedocs -Projekteinstellungen an.

FAQs:

(Der FAQ -Teil im Originaldokument wird hier weggelassen, da der Artikel zu lang ist und der Inhalt vom vorhandenen Inhalt zu grundlegend ist. Bei Bedarf können Sie die FAQ -Frage separat stellen.)

Zusammenfassung:

In diesem Artikel wird der vollständige Prozess des Erstellens von PHP -Projektdokumenten mithilfe von Sphinx und Redethedocs eingeführt. Mit angemessener Konfiguration und Themenanpassung können Sie schöne, einfach zu machende und einfach zugängliche Dokumente erstellen, die die Professionalität und Wartbarkeit Ihrer Projekte verbessern.

Das obige ist der detaillierte Inhalt vonVerwenden von Sphinx für PHP -Projektdokumentation. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!