benlk/notes.md

## notes.md

      
    Raw
  

              notes.md
            
          
    The goal of this project is to use Phpdoc against Largo to generate GitHub Wiki pages using phpdoc and phpdoc-md.
The entirety of their documentation on templates and custom templates:

http://www.phpdoc.org/templates
http://www.phpdoc.org/docs/latest/getting-started/changing-the-look-and-feel.html
http://www.phpdoc.org/docs/latest/references/configuration.html

Thoughts:

I had the 1.4 version of phpdoc, from the wrong PEAR repo. setup.md has been updated to reflect the proper way to get the current version of phpdoc.
current permissions problems with new templates should be solved by the chmod command in setup.md
haven't tested the new "structure.xml" theme yet, or posted it here.


## setup.md

      
    Raw
  

              setup.md
            
          
    Setting up phpdoc

From: http://icdif.com/computing/2011/01/29/install-phpdocumentor-ubuntu-linux/
On a machine with a localhost webserver in /var/www:
sudo apt-get install php-pear
sudo pear config-set data_dir /var/www
sudo pear channel-discover pear.phpdoc.org
sudo pear install phpdoc/phpDocumentor
sudo mkdir /var/www/phpdoc-output
cd /var/www/
sudo chown www-data:www-data phpdoc-output

Then visit http://localhost/PhpDocumentor in a browser. If you see the PHPDocumentor web GUI, success. Move on to the next section.
Setting up PHPDocMD

From: http://www.charlestonsw.com/making-github-wiki-docs-from-php-source/
In a new directory, anywhere:
git clone git@github.com:evert/phpdoc-md.git
cd phpdoc-md/src
git clone git@github.com:fabpot/Twig.git
cd ../bin

Open phpdocmd in your favorite text editor, and replace the following:
<?php

// Potential composer autoloader paths
$paths = array(
	__DIR__ . '/../vendor/autoload.php',
	__DIR__ . '/../../../autoload.php',
);

foreach($paths as $path) {

	if (file_exists($path)) {
	    include $path;
	    break;
	}

}

// Everts crappy option parser.	

With this:
<?php

$docmdDir = dirname("PUT THE PHPDocMD DIR HERE"); // seriously, put it here
set_include_path(get_include_path().PATH_SEPARATOR.$docmdDir.'/../src/Twig/lib');

// Potential composer autoloader paths
foreach($paths as $path) {
	if (file_exists($path)) {
	    include $path;
	    print "including $path\n";
	    break;
	}
}

Twig_Autoloader::register();

// Everts crappy option parser.

Save it.
Generating documentation

Get a copy of your project:
git clone git@github.com:INN/Largo.git
mkdir docs
phpdoc -d ./Largo -t ./docs 

If you get a permissions error, chmod 766 the templates directory named in the error message. That should fix this error.
In the older version on phpdoc, it used to generate a structure.xml file, but that is no longer the default behavior.
Try running phpdocs with the following option: --template="clean".