how to create phpdoc Tutorial / Extended pages to supplement commented code

Question

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

Answer 1

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?

Answer 2

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.

Answer 3

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 [1].

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial%5Ftutorials.pkg.html#howto.location