1074

phpDocumentor for Trongate docs?

Comments for “phpDocumentor for Trongate docs?”
 

Posted by ak1 on Sunday 19th May 2024 at 11:54 GMT

Hi Trongate team,

This is just an idea, rather than a request for assistance.

Given the current priority on documenting the framework, have you considered using phpDocumentor (phpdoc.org)? Sorry if this is an obvious point or something that has been discussed before.

Granted, it won't write doc blocks for you, that still has to be done manually, nor, at first glance, does it seem to incorporate examples. But still, leveraging the existing doc blocks, from a test I just ran, it built a complete HTML doc site, including JS-powered search, for the Trongate framework in under 20 seconds.

(That was on Windows. I couldn't get it to work on Linux, for whatever reason. A "gotcha" I encountered: use this syntax when running from the terminal:
php path/to/phpDocumentor.phar run -d path/to/trongate-framework -t path/to/output/directory
. Including
run
proved to make all the difference. Without it, the tool just crashes. I mention this because some examples online include the "run" while others don't.)

The default HTML template would need modifications to bring it in line with the Trongate style, but other than that, this seems like a very suitable tool for the job.

Anyway, just thought I'd bring this up.

Cheers.
Level One Member

ak1

User Level: Level One Member

Date Joined: 16/01/2023

Posted by DaFa on Monday 20th May 2024 at 06:40 GMT

Hi there,

We have looked at auto-generating the docs previously, thanks for the suggestion.
I gave this tool a try and yeah it's very easy to use and fast.
Here is what it produced
https://ums.myds.me/tg_docs
which took 2 seconds to generate. There were deprecated warnings from one of its many 3rd party libraries...
Dom has used another tool called 'Doxygen'
https://vtlsoftware.co.uk/trongatedocs
but none of these generators gives the results we are looking for.

Cheers!
Founding Member

DaFa

User Level: Founding Member

Date Joined: 30/11/2018

Posted by ak1 on Monday 20th May 2024 at 11:47 GMT

Thanks for taking a look!

Yeah, I saw that it uses Twig, among other dependencies, after my previous comment, which I'm not thrilled about either.

For anyone else who might want to play around with this, this is as far as I got:

php path/to/phpDocumentor.phar run -d path/to/trongate-framework -t path/to/output/directory -s template.color=deep-purple --defaultpackagename Trongate --title="Trongate Docs" --visibility=public --ignore=*/views --ignore=public


You can add as many --ignore flags as you like, to filter out directories that shouldn't be documented. As a final note, when rebuilding, I found that it's just easier to delete the existing output directory and start over. Otherwise, the update behavior is a bit hit-or-miss, some things you'd expect to be documented aren't and vice versa.
Level One Member

ak1

User Level: Level One Member

Date Joined: 16/01/2023

×