CODEWITHSUNDEEP
phpdocumentationphpdoc
Ket Majmudar
Ket Majmudar

Reputation: 71

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

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

Upvotes: 3

Views: 2421

Answers (4)

ashnazg
ashnazg

Reputation: 6688

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.

Upvotes: 0

Rijk
Rijk

Reputation: 11301

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!

Upvotes: 0

Ket Majmudar
Ket Majmudar

Reputation: 71

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.

Upvotes: 3

André Hoffmann
André Hoffmann

Reputation: 3553

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?

Upvotes: 1

Related Questions