| Major trouble with PhpDocumentor [message #182308] |
Sun, 28 July 2013 01:25  |
Fiver
Messages: 35
Registered: July 2013
Karma:
|
Member |
|
|
Hi.
I've used PHPDoc and PhpDocumentor 1 in the past; it's always been a
pain in the neck to avoid the bugs in the software, but in the end they
did what I needed. Now I'm trying to run PhpDocumentor 2
(<http://phpdoc.org>), and after almost a full day of failed attempts,
I'm getting nowhere.
I really hope somebody familiar with this tool will read this, because I
can't find a dedicated forum or mailing list.
My current project uses features from PHP 5.4, including traits, the new
[array] syntax, and the const keyword (5.3). I've looked around, and
there aren't many docu processors that can handle these, so I'm more or
less depending on PhpDocumentor 2 to come through. Unfortunately, it
appears that this project hasn't quite recovered from the major rewrite
between v1 and v2 yet.
First, I tried to install it using the "recommended" method (via PEAR).
The following was run on an up-to-date Kubuntu Raring (13.04) box.
tl;dr: I installed phpDocumentor-beta and all available templates
------------------------------------------------------------------
root@example:~ # pear channel-discover pear.phpdoc.org
Adding Channel "pear.phpdoc.org" succeeded
Discovery of channel "pear.phpdoc.org" succeeded
root@example:~ # pear remote-list -c phpdoc
Channel phpdoc Available packages:
==================================
Package Version
phpDocumentor -n/a-
phpDocumentor_Template_abstract 1.0.3
phpDocumentor_Template_checkstyle 1.0.0
phpDocumentor_Template_new_black 1.0.4
phpDocumentor_Template_old_ocean 1.0.2
phpDocumentor_Template_responsive 1.0.1
phpDocumentor_Template_zend 1.0.2
root@example:~ # pear install phpdoc/phpDocumentor
Failed to download phpdoc/phpDocumentor within preferred state "stable",
latest release is version 2.0.0b7, stability "beta", use
"channel://pear.phpdoc.org/phpDocumentor-2.0.0b7" to install
install failed
root@example:~ # pear install phpdoc/phpDocumentor-beta
downloading phpDocumentor-2.0.0b7.tgz ...
Starting to download phpDocumentor-2.0.0b7.tgz (2,132,561 bytes)
...... (snip dots) ................done: 2,132,561 bytes
install ok: channel://pear.phpdoc.org/phpDocumentor-2.0.0b7
root@example:~ # pear install phpdoc/phpDocumentor_Template_abstract \
> phpdoc/phpDocumentor_Template_checkstyle \
> phpdoc/phpDocumentor_Template_new_black \
> phpdoc/phpDocumentor_Template_old_ocean \
> phpdoc/phpDocumentor_Template_responsive \
> phpdoc/phpDocumentor_Template_zend
downloading phpDocumentor_Template_abstract-1.0.3.tgz ...
[ snip: all templates installed fine ]
------------------------------------------------------------------
So far, so good; I can now run `phpdoc template:list` and get the
following output:
Available templates:
* checkstyle
* abstract
* zend
* new_black
* responsive-twig
* responsive
* xml
* old-ocean
* new-black
* old_ocean
As it turns out, only two of these 10 (8 without dupes) are even
remotely usable.
The following error out:
* abstract; responsive; zend:
Error: Structure.xml file was not found in the target directory, is
the XML writer missing from the template definition?
* new_black; old_ocean:
Error: Writer "Search" does not exist
These run, but will do nothing useful (without a major effort):
* checkstyle; xml:
Output is a single XML file without stylesheet.
* new-black:
No errors, but also no visible data.
The two that "worked":
* old-ocean:
Works, but will need serious adjustments to be readable (all classes
are duplicated; no links to source code; many tag values missing,
like @author or @version)
* responsive-twig:
The default template. Left navigation is missing; links are broken;
layout is broken; the toggle buttons only show up 10% of the time; no
links to source code.
Very disappointing.
Next, I tried the alternate install method (the .phar file). This seems
to work better, because it apparently contains more recent versions of
the templates. I don't get errors anymore, but the output is still very
unsatisfactory (same bugs as above).
I could bite the bullet and build my own template. For that I should
copy and adjust an existing current (and working) template. But I have
no idea where to find them! They're not included in the PhpDocumentor
repository, and <http://phpdoc.org/templates> only gives me screenshots
and names, but no code. Anyway, before I start that, I'd like to ask you:
Did any of you get this to work?
I know... it's beta software, but since v1 is now unmaintained and won't
be able to handle PHP 5.4, that's all there is.
I also looked at some alternate solutions:
- Doxygen: doesn't know about PHP's traits, namespaces, etc
- Sami: has a *million* dependencies, including Symfony, Composer,
Twig, and many others. This will be hard to deploy.
(but it's pretty)
- Doc-O-Matic, TwinText: Windows only
- phpSimpleDoc: 1 developer, no community, last release 2009
- Apple's HeaderDoc: not suited for PHP 5.4 at all
- ROBODoc: unique incompatible docu syntax, no PHP 5.4
I'm lost and open for any advice.
Thanks in advance,
5er
|
|
|
|
Calendar
Search
Help
Members
Register
Login
Home
]