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: . Including 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.
phpDocumentor for Trongate docs?
2 years ago
2 years ago
#1
2 years ago
#2
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 producedwhich took 2 seconds to generate. There were deprecated warnings from one of its many 3rd party libraries...
Dom has used another tool called 'Doxygen'but none of these generators gives the results we are looking for.
Cheers!
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 producedwhich took 2 seconds to generate. There were deprecated warnings from one of its many 3rd party libraries...
Dom has used another tool called 'Doxygen'but none of these generators gives the results we are looking for.
Cheers!
2 years ago
#3
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:
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.
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:
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.