PhpDoc's generated documents don't link together
我正试图对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中的重要位:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | 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"\ export PATH=$PATH:/var/www/magento/bin:/phpdoc/bin\ ">> /root/.bashrc |
第一个RUN是安装Magento的依赖项
第二次运行是在/ phpdoc上安装phpdoc
第三次运行是使phpdoc命令成为全局
Php版本为7.3.12
我必须使用phpdoc版本3,因为php版本是7。我试图在PhpDoc版本2上运行完全相同的设置,但它不起作用。我到处寻找解决方案,并且共识是PhpDoc无法解析php 7,因此我必须使用版本3。
PhpDoc似乎安装良好。它似乎也运行良好。我尝试在一个小文件夹(在
shell输出:
1 2 3 4 5 6 7 8 9 | 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内,并且看起来很正常。这是目录列表:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | 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的一部分:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 | root@78ace9205c9e:/var/www/docs# cat /var/www/docs/index.html | head -n 219 | tail -n 36 Block Adminhtml Frontend Region root@78ace9205c9e:/var/www/docs# |
如果您仔细注意,则链接的href为空。这基本上意味着文档几乎一文不值。这是视觉上的结果:
左侧的菜单看起来还不错,我可以探索树的结构。但是,当我单击1菜单项时,它只是返回到默认页面(这是预期的,因为href为空)。如果我直接转到名称空间的html文件(如/namespaces/Magento.Tax.html),则效果很好,看起来像这样:
一切似乎都正常,但神秘的链接却无效。任何帮助表示赞赏!
因此,在尝试其他php文档工具一段时间后,它们都无法正常运行。我猜这是因为php7太新了,几乎没有人使它工作。我对此的解决方案是只打开phpstorm中的每个文件,让它完成索引所有内容的艰苦工作,并将其用作临时文档。