xkratosx — 2012-08-17T12:52:43-04:00 — #1
I've just spent hours trying to generate PHP documentation for our systems, probably around 800 pages in total and very well commented so figured it'd be a good idea to have it generated automatically. Unfortunately anything I've tried (namely APIgen and phpDocumentor) have required either weird access permissions or internet connections which aren't available on the server - basically every single thing I've tried results in some kind of error.
Is there any alternative I've overlooked, preferably something that can just scan a directory and generate documentation accordingly? I've already spent hours on it I know, but if I can get something that'll work it'll save me weeks, potentially even longer in not having to re-write and collate all of my code and comments.
logic_earth — 2012-08-17T13:41:13-04:00 — #2
Why don't you do it on your personal computer? If you have access to the source code then simply downloading the code to your computer and running the documentation generation there...should avoid the issues you faced.
xkratosx — 2012-08-17T14:54:48-04:00 — #3
Thanks - I would do but it's on a work machine and I wouldn't be allowed (nor have the access) to install PHP on my own machine
jgetner — 2012-08-17T15:33:08-04:00 — #4
I would suggest doing it manually!. The reasons manually work so much better is you can be more verbose allowing for a better understanding of your API. Sure it might take you longer but when it is better it usually takes longer.
xkratosx — 2012-08-17T15:41:40-04:00 — #5
Thank you, but that's a luxury I really can't afford right now - it'd take weeks minimum, but most likely months to fully document all of the systems we have manually - there are so many people losing their jobs (I work for the police, UK) right now and so much to do I really don't think I can justify taking that much time out
Also, I've always gone out of my way to really document code well just to avoid ever having to go back and write loads of documentation
jgetner — 2012-08-17T15:46:56-04:00 — #6
your only other option if you don't want to use the above systems would be write a simple parser to read the comments into files or onto a web page or where ever. Than do it file by file or directory by directory.
But this point just gave me an idea to write a new Doc system...
xkratosx — 2012-08-17T16:55:41-04:00 — #7
Haha, yeah that's what I was almost hoping for - something with a frontend/GUI that would just scan the files for functions, comments, classes etc... basically do everything the others would do, without actually needing to be run via command line (even having something with a PHP frontend would be cool!)
xkratosx — 2012-08-20T06:02:23-04:00 — #8
Trying to run phpDocumentor on my local machine now and getting exactly the same errors as I was getting on the server - the firewall blocks both the PEAR and manual installations, I've tried downloading directly from GitHub and installing, I get as far as it trying to generate the documentation but it fails because important files (such as phpDocumentor.ini) are not part of the GitHub install.
Really not sure what to try next - I've asked and I can't take my code away from work, but I cannot generate any documentation from any of the methods online... why has no one made a GUI documenter that doesn't require messing with services, paths etc etc?
xkratosx — 2012-08-20T06:17:13-04:00 — #9
This is my path, and I'm still receiving 'php.exe is not recognised' errors...!