current community

your communities

more stack exchange communities

Stack Exchange
tour help
stack overflow careers
Take the 2-minute tour ×
Stack Overflow is a question and answer site for professional and enthusiast programmers. It's 100% free, no registration required.
up vote 4 down vote favorite
2

I'm trying everything I can to get phpdocumentor to allow me to use the DocBook tutorial format to supplement the documentation it creates:

  1. I am using Eclipse
  2. I've installed phpDocumentor via PEAR on an OSX machine
  3. I can run and auto generate code from my php classes
  4. It won't format Tutorials - I can't find a solution

I've tried moving the .pkg example file all over the file structure, in subfolders using a similar name to the package that is being referenced within the code .. I'm really at a loss - if someone could explain WHERE they place the .pkg and other DocBook files in relation to the code they are documenting and how they trigger phpdoc to format it I would appreciate it, I'm using this at the moment:

phpdoc -o HTML:Smarty:HandS
-d "/path/to/code/classes/", "/path/to/code/docs/tutorials/"
-t /path/to/output
share|improve this question

4 Answers 4

up vote 3 down vote accepted

I didn't expect to be answering my own question, but after 2 days of mind bending pain and a weekend to experiment it seems this is the problem:

The tutorial and my examples should work, but there seems to be a minor flaw in the way phpdoc interprets the switch values. Here is what I've been using:

phpdoc -o HTML:Smarty:HandS
-d "/path/to/code/classes/", "/path/to/code/docs/tutorials/"
-t /path/to/output

However if you use the following:

    phpdoc -o HTML:Smarty:HandS 
-d /path/to/code/classes/, /path/to/code/docs/tutorials/
-t /path/to/output

It will correctly format your tutorials and extending docs, all I did was drop the double quotes surrounding the directory paths. Single quotes don't work at all - as phpdoc itself wraps the directories in double quotes if there are no spaces ... this does seem like a bug with phpdoc, and the same behaviour occurred with the web based interface, so its an internal issue. my original attempt should have worked but didn't I will contact the developers and bring it to their attention.

Problem solved.

share|improve this answer
up vote 1 down vote

Have you read this?

It suggest the following path scheme: tutorials/package/package.pkg where package is the name of your package, did you do it this way?

share|improve this answer
    
Yes, I read that page in the documentation, many times. It recommends using <i>tutorials/package/package.pkg</i> - and I tried that scheme in about 4-5 locations - none of which made any difference. I also tried using just the individual name of the package as I couldn't get that to work. initially i had it set up as: /path/to/docs/tutorials/package/package.pkg then: /path/to/code/tutorials/package/package.pkg then: /path/to/tutorials/package/package.pkg then: /path/to/docs/tutorials/package.pkg I think there may have been 2-3 more diff attempts as well. –  Ket Majmudar Aug 7 '09 at 8:03
    
Well that's odd. Have you checked the permissions of the file? –  André Hoffmann Aug 7 '09 at 9:52
    
DO you know what permissions the file should be - i've not checked it and would imagine it only needs to be readable by the user - I could try running the command as root, I will check. –  Ket Majmudar Aug 7 '09 at 15:24
    
I am using location: trunk/tutorials/package/package.pkg and including -d trunk/tutorials/ in the command line. As a result I get: Tutorial/Extended Documentation Parsing Stage - done - so nothing happens. Where would I expect to see the docbook contents within the output folder if it did work ? –  Ket Majmudar Aug 7 '09 at 15:30
    
Wondering if this could have something to do with the .ini file - can't figure out why .pkg / .proc does not get recognised when the documentation builds ... –  Ket Majmudar Aug 9 '09 at 23:32
up vote 0 down vote

I was experiencing the same issue using an .ini for configuration, but with me the problem was that I put a space in between the comma and the directory, which resulted in the directory not being 'linked' to the -d parameter.

Not working:

directory = {$lib}/Question,{$lib}/Error, {$path}/docs/tutorials

Working:

directory = {$lib}/Question,{$lib}/Error,{$path}/docs/tutorials

Hope this solves the problem for someone else!

share|improve this answer
up vote 0 down vote

Yes, your usage of the double quotes probably threw off phpDocumentor's internal runtime argument parsing, causing -d /path/to/code/classes to be one arg/value pair, without including /path/to/code/docs/tutorials as an additional directory value.

Typically, I've seen two other issues around tutorials not being created. One, the tutorial directory isn't what phpDocumentor expects. Two, no actual PHP code files are included in the execution. I remember adding verbiage to the manual specifically for these two scenarios.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.