【问题标题】：PhpDoc's generated documents don't link togetherPhpDoc 生成的文档没有链接在一起
【发布时间】：2019-12-10 19:42:50
【问题描述】：

我试图对 Magento 进行逆向工程，我认为阅读每种方法都是一个好的开始（官方文档太浅了）。 Magento 似乎没有预先生成的文档，这是公平的，因为每个配置都彼此不同，并且一般地记录它是没有意义的。代码库中有 DocBlocks，我想我可以使用 PhpDoc 为其生成文档。

设置

Magento 发行版是 2.3.3，取自他们的 github 页面：https://github.com/magento/magento2/archive/2.3.3.tar.gz

环境位于 Docker Ubuntu 容器中，版本 18.04.3 LTS。以下是 Dockerfile 中的重要部分：

RUN apt-get -y install php-bcmath \
        php-curl \
        php-gd \
        php-intl \
        php-soap \
        php-zip \
        php-mbstring \
        #php-dom \
        php-xml \
        php-mysql \
        composer
RUN mkdir /phpdoc \
        && wget -O /phpdoc.tar.gz https://github.com/phpDocumentor/phpDocumentor/archive/v3.0.0-alpha.4.tar.gz \
        && tar -xvpzf /phpdoc.tar.gz -C /phpdoc --strip-component=1 \
        && cd /phpdoc \
        && composer install
RUN echo "\nexport PATH=$PATH:/var/www/magento/bin:/phpdoc/bin\n" >> /root/.bashrc

第一个RUN是安装Magento的依赖第二个 RUN 是在 /phpdoc 安装 phpdoc 第三个RUN是让phpdoc命令全局化

php版本是7.3.12

我必须使用 phpdoc 版本 3，因为 php 版本是 7。我尝试在 PhpDoc 版本 2 上运行完全相同的设置，但它不起作用。我四处寻找解决方案，一致认为 PhpDoc 无法解析 php 7，所以我必须使用版本 3。

PhpDoc 似乎安装得很好。它似乎也运行良好。我尝试在一个小文件夹（/var/www/magento/app/code/Magento/Tax，其中/var/www/magento 是文档根目录）上运行它来测试一下

shell 输出：

root@78ace9205c9e:/var/www/magento/app/code/Magento# phpdoc -d Tax -t /var/www/docs     
phpDocumentor vNo version set (parsed as 1.0.0)@

Parsing files

Applying transformations (can take a while)
 17/17 [============================] 100%
All done!
root@78ace9205c9e:/var/www/magento/app/code/Magento#

文件也整齐地位于 /var/www/docs 内，看起来很正常。这是目录列表：

root@78ace9205c9e:/var/www/docs# ls -la
total 472
drwxr-xr-x 11 root root   4096 Dec 10 16:20 .
drwxr-xr-x  1 root root   4096 Dec 10 17:05 ..
-rw-r--r--  1 root root    229 Dec 10 19:09 .htaccess
drwxr-xr-x  2 root root  90112 Dec 10 18:56 classes
drwxr-xr-x  3 root root   4096 Dec 10 16:20 css
drwxr-xr-x 70 root root  94208 Dec 10 18:56 files
drwxr-xr-x  2 root root   4096 Dec 10 16:20 font
drwxr-xr-x  2 root root   4096 Dec 10 16:20 graphs
drwxr-xr-x  3 root root   4096 Dec 10 16:20 images
-rw-r--r--  1 root root 202668 Dec 10 19:09 index.html
drwxr-xr-x  3 root root   4096 Dec 10 16:20 js
drwxr-xr-x  2 root root  49152 Dec 10 18:55 namespaces
drwxr-xr-x  2 root root   4096 Dec 10 16:20 reports
root@78ace9205c9e:/var/www/docs#

问题

这是文件 /var/www/docs/index.html 的一部分：


root@78ace9205c9e:/var/www/docs# cat /var/www/docs/index.html | head -n 219 | tail -n 36
                                                    <div class="accordion" style="margin-bottom: 0">
        <div class="accordion-group">
            <div class="accordion-heading">
                                    <a class="accordion-toggle collapsed" data-toggle="collapse" data-target="#namespace-306007264"></a>
                                <a href="" style="margin-left: 30px; padding-left: 0">Block</a>
            </div>
            <div id="namespace-306007264" class="accordion-body collapse ">
                <div class="accordion-inner">

                                                    <div class="accordion" style="margin-bottom: 0">
        <div class="accordion-group">
            <div class="accordion-heading">
                                    <a class="accordion-toggle collapsed" data-toggle="collapse" data-target="#namespace-954821111"></a>
                                <a href="" style="margin-left: 30px; padding-left: 0">Adminhtml</a>
            </div>
            <div id="namespace-954821111" class="accordion-body collapse ">
                <div class="accordion-inner">

                                                    <div class="accordion" style="margin-bottom: 0">
        <div class="accordion-group">
            <div class="accordion-heading">
                                    <a class="accordion-toggle collapsed" data-toggle="collapse" data-target="#namespace-289993205"></a>
                                <a href="" style="margin-left: 30px; padding-left: 0">Frontend</a>
            </div>
            <div id="namespace-289993205" class="accordion-body collapse ">
                <div class="accordion-inner">

                                                    <div class="accordion" style="margin-bottom: 0">
        <div class="accordion-group">
            <div class="accordion-heading">
                                    <a class="accordion-toggle collapsed" data-toggle="collapse" data-target="#namespace-1022188315"></a>
                                <a href="" style="margin-left: 30px; padding-left: 0">Region</a>
            </div>
            <div id="namespace-1022188315" class="accordion-body collapse ">
                <div class="accordion-inner">

root@78ace9205c9e:/var/www/docs#

如果您仔细观察，链接的 href 是空的。这基本上意味着文档几乎毫无价值。这是视觉上的结果：

左边的菜单看起来还可以，我可以探索一下树形结构。但是当我点击 1 个菜单项时，它只是返回到默认页面（这是预期的，因为 href 是空的）。如果我直接转到命名空间的 html 文件，例如 /namespaces/Magento.Tax.html，它就可以正常工作，看起来像这样：

一切似乎都运行良好，但神秘的链接不起作用。任何帮助表示赞赏！

【问题讨论】：

标签： php magento2 phpdoc

【解决方案1】：

所以在尝试了其他 php 文档工具之后，它们都不能正常工作。我想这是因为 php7 太新了，几乎没有人让它工作。我对此的解决方案是在 phpstorm 中打开每个文件并让它完成索引所有内容的艰巨工作，并将其用作临时文档。

【讨论】：