PhpDoc's generated documents don't link together
I was trying to reverse engineer Magento and I thought that reading over every method is a good start (the official docs are too shallow). Magento doesn't appear to have pre-generated docs, which is fair, because each configuration is different from the other, and wouldn't make sense to document it generically. There are DocBlocks inside the code base and I thought I can just use PhpDoc to generate docs for it.
The setup
Magento distribution is 2.3.3, taken from their github page: https://github.com/magento/magento2/archive/2.3.3.tar.gz
The environment is in a Docker Ubuntu container, version 18.04.3 LTS. Here are the important bits inside the 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
The first RUN is to install Magento's dependencies The second RUN is to install phpdoc at /phpdoc The third RUN is to make the phpdoc command global
Php version is 7.3.12
I have to use phpdoc version 3 because the php version is 7. I tried running the exact same setup on PhpDoc version 2 and it doesn't work. I look around for solutions and the consensus is that PhpDoc can't parse php 7, so I have to use version 3.
PhpDoc appears to install well. It appears to run well too. I try to run it on a small folder (at /var/www/magento/app/code/Magento/Tax where /var/www/magento is the document root) to test things out
The shell output:
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#
The files are neatly inside of /var/www/docs too and appears to be normal. This is the directory listing:
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#
The problem
This is a part of file /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#
If you notice carefully, the hrefs of the links are empty. This basically means the docs are pretty much worthless. This is the result visually:
The menu on the left looks okay, and I can explore the tree structure. But when I click on 1 menu item, it just returns to the default page (which is expected, because the hrefs are empty). If I go directly to a namespace's html file, like /namespaces/Magento.Tax.html, it works just fine and looks like this:
Everything seems to be working just fine, but the links mysteriously just don't work. Any help is appreciated!
So after a while trying other php documentation tools, and they all don't work as well. I guess this is because of php7 is so new that pretty much no one has made it work just yet. My solution to this is to just open every file in phpstorm and let it do the hard job of indexing everything, and just use that as a makeshift documentation.