Utilisation de Sphinx pour la documentation du projet PHP

Rédiger efficacement Documentation du projet PHP: Guide SPHINX et ReadTheDocs

Cet article vous guidera comment utiliser Sphinx et ReadTheDocs pour créer des documents de projet PHP de haute qualité, couvrant des étapes clés telles que l'installation, la personnalisation du thème, la mise en évidence de la syntaxe PHP, le déploiement de ReadTheDocs, etc.

Points de base:

• L'installation SPHINX s'intègre aux lectures: Utilisez SPHinx pour combiner ReadTheDocs, prendre en charge les formats de repos et de démarrage pour créer facilement des documents de projet PHP professionnels.
• Structure du dossier recommandé: Pour optimiser l'organisation du projet, il est recommandé de placer les documents et le code de projet dans le même dossier, ou créer un référentiel de code indépendant basé sur la taille du projet.
• Thème personnalisé: Améliorez l'esthétique des documents et améliorez l'expérience utilisateur par l'installation et la configuration. sphinx_rtd_theme
• PHP Syntaxe Fait de surlimination et configuration du domaine: Installez Extension pour implémenter la mise en surbrillance de la syntaxe du code PHP et la prise en charge du langage PHP plus précise pour améliorer la lisibilité du code. sphinxcontrib-phpdomain
• ReadTheDocs Déploiement et extension: Déployez des documents pour lire lesocs pour un accès et une gestion faciles et utiliser des améliorations d'extension.

ReadTheDocs est une plate-forme d'hébergement de documents largement utilisée dans l'industrie. Il prend en charge la construction locale et l'hébergement en ligne, ce qui facilite le contrôle des développeurs et la collaboration par équipe.

Démarrage rapide:

Les commandes suivantes peuvent rapidement construire l'environnement du document Sphinx:

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

Activer le thème et la syntaxe PHP qui met en évidence après avoir terminé le démarrage rapide:

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

Créer un document HTML:

make html

ou

sphinx-build -b html source build

Installation de Sphinx:

readTheDocs utilise sphinx dans la couche sous-jacente, donc Sphinx et ses dépendances doivent être installés. Utilisez

pour installer les outils nécessaires. pip install sphinx sphinx-autobuild

Structure du dossier recommandé:

Les documents peuvent être placés dans le même dossier que le code de projet ou dans un référentiel de code séparé. Il est recommandé que les petits projets placent des documents dans les dossiers de projet, tels que

. Utilisez des fichiers my-php-project/docs pour exclure facilement les documents des versions de projet. .gitattributes

Thème personnalisé:

Utilisez

Installation du thème pip install sphinx_rtd_theme et configurez-le dans le fichier 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()]

Structure du répertoire:

Dans le processus

, vous devez spécifier le nom du fichier de document principal (généralement sphinx-quickstart). Le document principal utilise la commande index.rst pour générer le répertoire: toctree

.. toctree::
   :maxdepth: 2

   overview
   quickstart

Syntaxe PHP Fait saillie:

Ajoutez le code suivant au fichier source/conf.py pour activer la motivation de la syntaxe 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

Field PHP:

Installer sphinxcontrib-phpdomain Prise en charge du langage PHP amélioré étendu: sudo pip install sphinxcontrib-phpdomain et activer: conf.py dans extensions = ["sphinxcontrib.phpdomain"].

Afficher le code source:

Ajoutez le code suivant dans conf.py pour afficher le lien de code source GitHub dans le document:

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 and Markdown:

SPHINX prend en charge le repos et la marque. Installez recommonmark Extension pour prendre en charge Markdown: sudo pip install recommonmark et configurez dans conf.py:

make html

Déplacement de lecture des liens:

Créez un nouveau projet sur ReadTheDocs, connectez votre référentiel GitHub pour créer et déployer automatiquement des documents.

EXTENSION DE LEATHEDOCS:

Créez un fichier requirements.txt pour répertorier les dépendances et spécifiez le chemin du fichier dans les paramètres du projet ReadTheDocs.

FAQS:

(La partie FAQ du document d'origine est omise ici car l'article est trop long et le contenu est dupliqué ou trop basique à partir du contenu existant. Si nécessaire, vous pouvez poser la question de la FAQ séparément.)

Résumé:

Cet article présente le processus complet de création de documents de projet PHP à l'aide de Sphinx et de ReadTheDocs. Avec une configuration raisonnable et une personnalisation du thème, vous pouvez créer de beaux documents faciles à maintenir et facile à accès qui améliorent le professionnalisme et la maintenabilité de vos projets.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!