Summary
After installing phpSimpleDoc, you need to understand four things before starting to use it :
-
phpSimpleDoc can be used from a web browser or from a console. See page Web or console for details.
-
The interactions between you and phpSimpleDoc are done through .ini files, called "user directives files" ; they contain the directives given to phpSimpleDoc to generate a documentation : path to the source files to document, title of the program program etc. See page User directives for a complete list of directives.
-
To generate the documentation, phpSimpleDoc parses the php code to reconstitute the structure of your program, and uses special comments, called "doc comments", that use javadoc syntax. See page Syntax of doc comments for details.
-
To generate documentation, phpSimpleDoc uses the notion of package, to group code elements. Depending on how your code is organized, you must indicate to phpSimpleDoc how it will form packages. See page Packages.
Installation
Download the archive and uncompress it ; this generates a directory
phpsimpledoc/.
If you visit this directory, you should see this hierarchy :
phpsimpledoc/
|-- docs // A local copy of this user guide
|-- output // An empty directory, used to store generated documentation
|-- src // The program itself
`-- user-directives // The directory containing user directives, for web usage
Testing phpSimpleDoc
To see if everything works fine, you can generate phpSimpleDoc's API documentation as a first test.
- Edit the file
/path/to/phpsimpledoc/user/examples/phpSimpleDoc.ini
- Modify the following lines :
sourceDir = /path/to/phpsimpledoc/src
outputDir = /path/to/phpSimpleDoc/output/phpsimpledoc
You need to adapt the paths to your own machine, and make sure that php has write permissions on output directory.
You must specify absolute paths.
- Supposing that you have an operational web server (like apache) installed on your machine, and assuming that directory
phpsimpledoc is visible by your web server, visit page :
http://localhost/path/to/phpsimpledoc/src/index.php (adapt the path).
- Click on link "phpSimpleDoc"
- Normally, the generated documentation is located on the output directory
Possible problem
At first execution, you may have a message "I/O Problem : impossible to open file tmp_parseinifile2".
To fix it, PHP must have write permissions on directories 'src', 'src/libext' and 'src/libext/utils' :
cd /path/to/phpsimpledoc
chmod 777 src
chmod 777 src/libext
chmod 777 src/libext/utils
(this problem occurs while parsing configuration file ; a temporary file is created and deleted in directory src/libext/utils).
Generating your own documentation
Once you've seen that the program is running, you can generate documentation for your own program.
-
The first step is to decide which method phpSimpleDoc will use to form packages ; read page Packages.
-
The second step is to write the corresponding .ini file containing the directives. To make this easier, you have two files at your disposition :
- /path/to/phpsimpledoc/user-directives/examples/example-short.ini
- /path/to/phpsimpledoc/user-directives/examples/example-full.ini
example-full.ini contains the full list of available directives.
As default values are often suitable, example-short.ini contains the bare minimum for a quick start.
-
The last step is to order the run, either from command line or from a web browser.
Form a web browser, visit page : http://localhost/path/to/phpsimpledoc/src/index.php.
A link containing the name of your software should appear (relooad the page if you don't see it).
Click on this link to generate the documentation.
For command line usage, see page Web or console.
Good luck !
