README

由 AeonDigital 从 Francesco "Abbadon1334" Danti 分支出来的。
在这个分支中，更改只有视觉和表面效果[只是因为我很无聊 :) ]。
如果你更喜欢一个持续更新的项目，请使用"Abbadon1334"版本。

使用 PHPDoc 提取技术文档。

Sphinx 的 reStructuredText 生成器

该项目大量基于 phpDocumentor/Reflection，并使用 PHP Domain for Sphinx。

依赖关系

Python
Sphynx
Sphinx RTD Theme
PHP Domain for Sphinx
Recommonmark

以下是一个快速教程，说明如何安装所有依赖项以正确运行。

Python 安装

访问官方网站并下载最新和最稳定的可执行文件

运行安装程序。

本教程是为 3.7.3 (windows) 版本制作的。

在第一个屏幕上选择将 Python 添加到 Windows PATH 的选项。
选择自定义安装。

您可以删除文档。
保留 pip。
您可以删除 Tkinter 库¹。
保留 Python Test Suite。
您还可以删除 py launcher²。
在下一个屏幕上配置您的偏好并安装。
安装完成后，程序会提示您禁用 Windows 中命令执行的限制。点击禁用此限制以避免执行时出现问题。

Sphinx 安装程序

现在 Python 已通过 "pip" 安装，打开一个命令提示符。
使用以下命令安装 "Sphinx"

> pip install -U sphinx

使用以下命令确认安装

> sphinx-build --version

RTD Theme 安装

了解更多关于 RTD Theme 的信息。

> pip install -U sphinx_rtd_theme

PHP Domain for Sphinx

了解更多 PHP Domain for Sphinx.

> pip install -U sphinxcontrib-phpdomain

Markdown 分析器安装

了解更多关于在 Sphynx 中使用 Markdown 的信息。

> pip install -U recommonmark

使用 Sphynx

建议为您的项目文档创建一个目录。默认情况下是根目录下的 [./docs] 目录。

特殊目录 [./docs/_static] 包含应与提取结果合并的文件，这些文件位于 [./docs/rest]。其中包含图像、样式表和配置文件 [conf.py]，后者必须根据每个项目进行编辑。

配置文件 "[conf.py]"

最初，您必须创建自己的 conf.py 文件，以便为文档从 reST 到其他格式的转换服务。
如果您不知道如何创建此文件以及其指令，我们建议您使用template-conf.py作为模板来开始创建自己的版本。

有关此文件如何工作及其主要配置的完整信息，您可以在https://sphinx-doc.cn/en/master/config查看。

您还可以使用config命令（见下文）来创建一个基本的conf.py版本，只需更改信息标签。

使用“phpdoc-to-rst generate”命令

将PHPDocs转换为RST
在此步骤中，本项目提供的分析器将负责读取项目目标中包含的所有PHPDocs注释，然后将其提取为reST格式。

从项目根目录开始
使用以下命令安装“phpdoc-to-rst”库

> composer require --dev aeondigital/phpdoc-to-rst

使用以下命令提取内容

> ./vendor/bin/phpdoc-to-rst generate <output_directory> <source_directory>

output_directory：提取文档将添加的目录名称。
source_directory：创建文档的源文件所在的目录名称。[通常为src].

示例

> ./vendor/bin/phpdoc-to-rst generate docs/rest src

使用“phpdoc-to-rst generate-ns”命令

仅提取一个namespace
如果您只想从项目中导出一个特定的namespace，请使用以下命令

> ./vendor/bin/phpdoc-to-rst generate-ns <namespace> <output_directory> <source_directory>

namespace：您要导出的namespace名称。
output_directory：提取文档将添加的目录名称。
source_directory：创建文档的源文件所在的目录名称。[通常为src].

示例

> ./vendor/bin/phpdoc-to-rst generate-ns JuliusHaertl/PHPDocToRst docs/rest src

使用“phpdoc-to-rst config”命令

准备“conf.py”文件
如果您还没有准备好的conf.py文件并放置在[./src/_static]目录中，也不知道从哪里开始，这是获取有效版本的最好方法，该版本可用于sphinx-build命令（见下文）。

使用以下命令开始配置

> ./vendor/bin/phpdoc-to-rst config

然后，遵循每个要配置项目的说明。
留空的条目将被定义为空字符串""。

使用Sphinx和“sphinx-build”命令

生成特定格式的输出
一旦您拥有了包含项目PHPDocs注释相关内容的所有reST文件，就是时候使用Sphynx将这批数据转换为其他格式，如HTML或Ebook。

从项目根目录开始

> sphinx-build -b <output_type> <source_directory> <output_directory>

output_type：文档输出格式[html, epub]
source_directory：创建文档的源文件所在的目录名称。
output_directory：提取文档将添加的目录名称。

示例

> sphinx-build -b html docs/rest docs/html  
> sphinx-build -b epub docs/rest docs/epub

重要

由于本项目是从由Abbadon1334开发并维护的版本派生出来的，目的是针对特定的视觉细节，因此请注意，此软件可能将落后于实现修正或新功能。

aeondigital / phpdoc-to-rst

维护者

详细信息