README
$Id: README,v 1.3 2006/04/30 18:38:56 cellog Exp $
################################################################################
phpDocumentor
################################################################################
Installation
################################################################################
Installation for phpDocumentor is as simple as installing PHP and a web server.
If you need help installing a webserver or php, refer to the documentation that
comes with the webserver or with php. phpDocumentor also runs from the command-line,
and only requires that PHP CLI version be installed.
All users with PEAR should either install this version directly from the package.xml
file included in the distribution, or install via "pear install PhpDocumentor." The
command-line interface "phpdoc" will be in the path, you can use it immediately
on both windows and unix. The web interface is in a subdirectory of your
document root, be sure to "pear config-set data_dir /path/to/my/htdocs" prior
to installation.
To use phpDocumentor as a command-line
tool in *nix-based systems, simply run the phpdoc script. In windows, run
"c:\php\php.exe phpdoc" where C:\php is the path to the cli version of php.
The phpdoc command-line interface will not run with the ISAPI module of PHP.
To see the command line options, use phpdoc -h or read at the bottom of this
README.
There is a BASH shell script that you can put inside your project that can save
time writing command-line options of phpdoc. Simply copy makedoc.sh to your
project path and edit it. When you wish to rebuild the documentation, run it again.
Note that .ini scripts are far easier to edit and are supported via "phpdoc -c file.ini"
To use phpDocumentor's web interface, install the files into a subdirectory of
your document root (read the webserver's documentation for more information if you
don't understand how to install into a subdirectory of your document root).
Then, browse to the web page as you would to any other web page. If you encounter
problems, make sure that the web server has write access permissions to the output
directory that you choose. Again, your web server documentation has detailed
information on how to do this. The command-line interface will not have problems
with access.
If you need more detailed help, check out INSTALL
################################################################################
Release Notes
################################################################################
Release notes for the newest version are in Release-1.3.0
1.3.0 is out, a STABLE release
To learn howto write PHPDoc-style documentation run phpDocumentor on itself, with
./phpdoc -c makedocs. Before you do, modify users/makedocs.ini to contain the
proper path values
If you find a bug please post it at:
http://sourceforge.net/tracker/?func=add&group_id=11194&atid=111194
################################################################################
General Notes
################################################################################
phpDocumentor is hosted at phpdoc.org, with downloads and mailing list through
sourceforge.net
webpage: http://phpdoc.org/
documentation: http://phpdoc.org/manual.php
mirror: http://phpdocu.sourceforge.net
projectpage: http://www.phpdoc.org
For a list of people who have helped work on this project please read the
Authors file
phpDocumentor 1.3.0 is released under the LGPL version 2.1, text is in
LICENSE
################################################################################
Feature Notes
################################################################################
phpDocumentor is a JavaDoc-like automatic documentation generator for PHP
written in PHP. It is the most versatile tool for documenting PHP.
For users new to phpDocumentor, phpDocumentor uses an event-driven parser
and intermediary data structures that allow it to perform at a level other
automatic documentors for PHP cannot achieve:
--parsing any php file, with multiple classes and functions in the same file
--fully compliant with even the most esoteric php syntax
($string = <<< EOF, for example)
--ability to generate multiple output formats
--extremely fast parsing
--error/warnings by line number and file to allow for debugging of
documentation tags
--multiple output templates to easily customize the look of generated
documentation
--extensive documentation of the package, including a detailed specification
for tags and templates
--PHP License
New in version 1.3.0:
--PHP 5 Parsing
--hundreds of bugfixes from version 1.2.3
If something is missing from this list make sure sure to file
a feature request on sourceforge
http://sourceforge.net/tracker/?func=add&group_id=11194&atid=361194
If you want to help code that new feature and get it just right, please let us know.
Any help is greatly appreciated, just contact the
phpDocumentor team for information on getting started.
phpDocumentor needs php 4.2.0 or greater, but you'll see the best performance
in the newest version. The recommended version for 1.3.0 is 5.1.3 or newer.
################################################################################
Command Line notes
################################################################################
Read the documentation at http://www.phpdoc.org/docs for the most up-to-date
command-line information.
You can also generate documentation from the source using:
phpdoc -c makedocs
run this command from the installation directory, and make sure you have full
write and directory creation permissions or it will not work
Generated documentation is accessible via Documentation/new/index.html
################################################################################
if you run phpdoc and get :
bash: ./phpdoc: No such file or directory
Then you haven't installed the cgi version of php
goto your php src dir and try
make clean
./configure
make
make install
phpdoc should work now
If your using php 4.2.0 or higher you will want to use the cli version
instead of the cgi. Checkout php.net for details on these changes
################################################################################
Web Interface notes
################################################################################
Put phpdoc.php together with the *.inc files someplace on your webserver.
NEVER USE THE WEB INTERFACE ON A PRODUCTION WEBSERVER. Allowing your server
to write files to disk is a serious security risk, and phpDocumentor is not
designed to work on insecure systems. Setup php on a development machine
that has a firewall or no internet connection, and run phpDocumentor from there.
Make sure you webserver can write to where ever you specify as a target or you
will get lots of errors
################################################################################
Thanks
################################################################################
Thanks to Sam Blum for his assistance with @example and other enhancements
Thanks to William K. Hardeman for his HTML:Smarty:HandS design
Thanks to Marco von Ballmoos for transforming the HTML:frames converter and
templates into a magnificent work of art
Thanks to Andrew Eddie for docbuilder and the CHM Converter enhancements
Thanks to Darren Cook for suggesting exciting new features, and making sure that
they worked when implemented
Thanks to Marko Kaening, Dan Convissor for policing the source and finding bugs
that would have otherwise gone undetected
Thanks to Juan Pablo Morales for the web interface.
Thanks to whoever sent me the patch to make phpdocumentor work better in NT
I have your diff and patched the program but i seem to have lost your
name if you send it to me i'll add it to the Authors file
Thanks to Florian Clever for the newest set of win32 patches they seem to have
fixed the last of the problems.
Thanks to EVERYONE who has provided ideas and input, without you,
phpDocumentor would be nothing
################################################################################
################################################################################
if you have any questions please email
joshua eichorn [email protected]
gregory beaver [email protected]
vim: set expandtab:
|
