Efficiently write PHP project documentation: Sphinx and ReadTheDocs Guide

This article will guide you how to use Sphinx and ReadTheDocs to create high-quality PHP project documents, covering key steps such as installation, theme customization, PHP syntax highlighting, ReadTheDocs deployment, etc.

Core points:

• Sphinx installation integrates with ReadTheDocs: Use Sphinx to combine ReadTheDocs, support reST and Markdown formats to easily create professional PHP project documents.
• Recommended folder structure: To optimize project organization, it is recommended to place the documents and project code in the same folder, or create an independent code repository based on the project size.
• Custom theme: Improve the aesthetics of documents and enhance user experience through installation and configuration. sphinx_rtd_theme
• PHP syntax highlighting and domain configuration: Install Extension to implement PHP code syntax highlighting and more accurate PHP language support to improve code readability. sphinxcontrib-phpdomain
• ReadTheDocs Deployment and Extension: Deploy documents to ReadTheDocs for easy access and management, and utilize extension enhancements.

ReadTheDocs is a widely used document hosting platform in the industry. It supports two markup languages: reST and Markdown, which is especially suitable for the writing of technical documents. It supports local build and online hosting, making it easier for developers to version control and team collaboration.

Quick Start:

The following commands can quickly build the Sphinx document environment:

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

Enable theme and PHP syntax highlighting after completing the quick startup:

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

Build HTML Document:

make html

or

sphinx-build -b html source build

Sphinx installation:

ReadTheDocs uses Sphinx in the underlying layer, so Sphinx and its dependencies need to be installed. Use

to install the necessary tools. pip install sphinx sphinx-autobuild

Recommended folder structure:

Documents can be placed in the same folder as the project code, or in a separate code repository. It is recommended that small projects place documents in project folders, such as

. Use my-php-project/docs files to easily exclude documents from project releases. .gitattributes

Custom theme:

Use

Installing the pip install sphinx_rtd_theme theme and configure it in the sphinx_rtd_theme file: source/conf.py

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

Directory structure:

In the

process, you need to specify the main document file name (usually sphinx-quickstart). The main document uses the index.rst command to generate the directory: toctree

.. toctree::
   :maxdepth: 2

   overview
   quickstart

PHP syntax highlighting:

Add the following code to the source/conf.py file to enable PHP syntax highlighting:

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:

Installsphinxcontrib-phpdomainExtended Enhanced PHP Language Support: sudo pip install sphinxcontrib-phpdomain and enable: conf.py in extensions = ["sphinxcontrib.phpdomain"].

View source code:

Add the following code in conf.py to display the GitHub source code link in the 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 supports reST and Markdown. Install recommonmark extension to support Markdown: sudo pip install recommonmark and configure in conf.py:

make html

ReadTheDocs deployment:

Create a new project on ReadTheDocs, connect your GitHub repository to automatically build and deploy documents.

ReadTheDocs extension:

Create a requirements.txt file to list dependencies and specify the file path in the ReadTheDocs project settings.

FAQs:

(The FAQ part in the original document is omitted here because the article is too long and the content is duplicated or too basic from the existing content. If necessary, you can ask the FAQ question separately.)

Summary:

This article introduces the complete process of creating PHP project documents using Sphinx and ReadTheDocs. With reasonable configuration and theme customization, you can create beautiful, easy-to-maintain and easy-to-access documents that improve the professionalism and maintainability of your projects.

The above is the detailed content of Using Sphinx for PHP Project Documentation. For more information, please follow other related articles on the PHP Chinese website!