Added Kohana v3.0.9

includes/kohana/modules/userguide/classes/controller/userguide.php

@@ -0,0 +1,391 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Kohana user guide and api browser.
+ *
+ * @package    Kohana/Userguide
+ * @category   Controllers
+ * @author     Kohana Team
+ */
+class Controller_Userguide extends Controller_Template {
+
+	public $template = 'userguide/template';
+
+	// Routes
+	protected $media;
+	protected $api;
+	protected $guide;
+
+	public function before()
+	{
+		if ($this->request->action === 'media')
+		{
+			// Do not template media files
+			$this->auto_render = FALSE;
+		}
+		else
+		{
+			// Grab the necessary routes
+			$this->media = Route::get('docs/media');
+			$this->guide = Route::get('docs/guide');
+
+			if (defined('MARKDOWN_PARSER_CLASS'))
+			{
+				throw new Kohana_Exception('Markdown parser already registered. Live documentation will not work in your environment.');
+			}
+
+			// Use customized Markdown parser
+			define('MARKDOWN_PARSER_CLASS', 'Kodoc_Markdown');
+
+			if ( ! class_exists('Markdown', FALSE))
+			{
+				// Load Markdown support
+				require Kohana::find_file('vendor', 'markdown/markdown');
+			}
+
+			// Set the base URL for links and images
+			Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/';
+			Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/';
+		}
+
+		parent::before();
+	}
+	
+	// List all modules that have userguides
+	public function index()
+	{
+		$this->template->title = "Userguide";
+		$this->template->breadcrumb = array('User Guide');
+		$this->template->content = View::factory('userguide/index', array('modules' => $this->_modules()));
+		$this->template->menu = View::factory('userguide/menu', array('modules' => $this->_modules()));
+		
+		// Don't show disqus on the index page
+		$this->template->hide_disqus = TRUE;
+	}
+	
+	// Display an error if a page isn't found
+	public function error($message)
+	{
+		$this->request->status = 404;
+		$this->template->title = "Userguide - Error";
+		$this->template->content = View::factory('userguide/error',array('message' => $message));
+		
+		// Don't show disqus on error pages
+		$this->template->hide_disqus = TRUE;
+
+		// If we are in a module and that module has a menu, show that
+		if ($module = $this->request->param('module') AND $menu = $this->file($module.'/menu') AND Kohana::config('userguide.modules.'.$module.'.enabled'))
+		{
+			// Namespace the markdown parser
+			Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/'.$module.'/';
+			Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
+		
+			$this->template->menu = Markdown($this->_get_all_menu_markdown());
+			$this->template->breadcrumb = array(
+				$this->guide->uri() => 'User Guide',
+				$this->guide->uri(array('module' => $module)) => Kohana::config('userguide.modules.'.$module.'.name'),
+				'Error'
+			);
+		}
+		// If we are in the api browser, show the menu and show the api browser in the breadcrumbs
+		else if (Route::name($this->request->route) == 'docs/api')
+		{
+			$this->template->menu = Kodoc::menu();
+
+			// Bind the breadcrumb
+			$this->template->breadcrumb = array(
+				$this->guide->uri(array('page' => NULL)) => 'User Guide',
+				$this->request->route->uri() => 'API Browser',
+				'Error'
+			);
+		}
+		// Otherwise, show the userguide module menu on the side
+		else
+		{
+			$this->template->menu = View::factory('userguide/menu',array('modules' => $this->_modules()));
+			$this->template->breadcrumb = array($this->request->route->uri() => 'User Guide','Error');
+		}
+	}
+
+	public function action_docs()
+	{
+		$module = $this->request->param('module');
+		$page = $this->request->param('page');
+
+		// Trim trailing slash
+		$page = rtrim($page, '/');
+
+		// If no module provided in the url, show the user guide index page, which lists the modules.
+		if ( ! $module)
+		{
+			return $this->index();
+		}
+		
+		// If this module's userguide pages are disabled, show the error page
+		if ( ! Kohana::config('userguide.modules.'.$module.'.enabled'))
+		{
+			return $this->error(__('That module doesn\'t exist, or has userguide pages disabled.'));
+		}
+		
+		// Prevent "guide/module" and "guide/module/index" from having duplicate content
+		if ( $page == 'index')
+		{
+			return $this->error(__('Userguide page not found'));
+		}
+		
+		// If a module is set, but no page was provided in the url, show the index page
+		if ( ! $page )
+		{
+			$page = 'index';
+		}
+
+		// Find the markdown file for this page
+		$file = $this->file($module.'/'.$page);
+
+		// If it's not found, show the error page
+		if ( ! $file)
+		{
+			return $this->error(__('Userguide page not found'));
+		}
+		
+		// Namespace the markdown parser
+		Kodoc_Markdown::$base_url  = URL::site($this->guide->uri()).'/'.$module.'/';
+		Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/';
+
+		// Set the page title
+		$this->template->title = $page == 'index' ? Kohana::config('userguide.modules.'.$module.'.name') : $this->title($page);
+
+		// Parse the page contents into the template
+		Kodoc_Markdown::$show_toc = true;
+		$this->template->content = Markdown(file_get_contents($file));
+		Kodoc_Markdown::$show_toc = false;
+
+		// Attach this module's menu to the template
+		$this->template->menu = Markdown($this->_get_all_menu_markdown());
+		
+		// Bind the breadcrumb
+		$this->template->bind('breadcrumb', $breadcrumb);
+		
+		// Bind the copyright
+		$this->template->copyright = Kohana::config('userguide.modules.'.$module.'.copyright');
+
+		// Add the breadcrumb trail
+		$breadcrumb = array();
+		$breadcrumb[$this->guide->uri()] = __('User Guide');
+		$breadcrumb[$this->guide->uri(array('module' => $module))] = Kohana::config('userguide.modules.'.$module.'.name');
+		
+		// TODO try and get parent category names (from menu).  Regex magic or javascript dom stuff perhaps?
+		
+		// Only add the current page title to breadcrumbs if it isn't the index, otherwise we get repeats.
+		if ($page != 'index')
+		{
+			$breadcrumb[] = $this->template->title;
+		}
+	}
+
+	public function action_api()
+	{
+		// Enable the missing class autoloader.  If a class cannot be found a
+		// fake class will be created that extends Kodoc_Missing
+		spl_autoload_register(array('Kodoc_Missing', 'create_class'));
+
+		// Get the class from the request
+		$class = $this->request->param('class');
+
+		// If no class was passed to the url, display the API index page
+		if ( ! $class)
+		{
+			$this->template->title = __('Table of Contents');
+
+			$this->template->content = View::factory('userguide/api/toc')
+				->set('classes', Kodoc::class_methods())
+				->set('route', $this->request->route);
+		}
+		else
+		{
+			// Create the Kodoc_Class version of this class.
+			$_class = Kodoc_Class::factory($class);
+			
+			// If the class requested and the actual class name are different
+			// (different case, orm vs ORM, auth vs Auth) redirect
+			if ($_class->class->name != $class)
+			{
+				$this->request->redirect($this->request->route->uri(array('class'=>$_class->class->name)));
+			}
+
+			// If this classes immediate parent is Kodoc_Missing, then it should 404
+			if ($_class->class->getParentClass() AND $_class->class->getParentClass()->name == 'Kodoc_Missing')
+				return $this->error('That class was not found. Check your url and make sure that the module with that class is enabled.');
+
+			// If this classes package has been disabled via the config, 404
+			if ( ! Kodoc::show_class($_class))
+				return $this->error('That class is in package that is hidden.  Check the <code>api_packages</code> config setting.');
+		
+			// Everything is fine, display the class.
+			$this->template->title = $class;
+
+			$this->template->content = View::factory('userguide/api/class')
+				->set('doc', Kodoc::factory($class))
+				->set('route', $this->request->route);
+		}
+
+		// Attach the menu to the template
+		$this->template->menu = Kodoc::menu();
+
+		// Bind the breadcrumb
+		$this->template->bind('breadcrumb', $breadcrumb);
+
+		// Get the docs URI
+		$guide = Route::get('docs/guide');
+
+		// Add the breadcrumb
+		$breadcrumb = array();
+		$breadcrumb[$this->guide->uri(array('page' => NULL))] = __('User Guide');
+		$breadcrumb[$this->request->route->uri()] = 'API Browser';
+		$breadcrumb[] = $this->template->title;
+	}
+
+	public function action_media()
+	{
+		// Get the file path from the request
+		$file = $this->request->param('file');
+
+		// Find the file extension
+		$ext = pathinfo($file, PATHINFO_EXTENSION);
+
+		// Remove the extension from the filename
+		$file = substr($file, 0, -(strlen($ext) + 1));
+
+		if ($file = Kohana::find_file('media/guide', $file, $ext))
+		{
+			// Check if the browser sent an "if-none-match: <etag>" header, and tell if the file hasn't changed
+			$this->request->check_cache(sha1($this->request->uri).filemtime($file));
+			
+			// Send the file content as the response
+			$this->request->response = file_get_contents($file);
+		}
+		else
+		{
+			// Return a 404 status
+			$this->request->status = 404;
+		}
+
+		// Set the proper headers to allow caching
+		$this->request->headers['Content-Type']   = File::mime_by_ext($ext);
+		$this->request->headers['Content-Length'] = filesize($file);
+		$this->request->headers['Last-Modified']  = date('r', filemtime($file));
+	}
+
+	public function after()
+	{
+		if ($this->auto_render)
+		{
+			// Get the media route
+			$media = Route::get('docs/media');
+
+			// Add styles
+			$this->template->styles = array(
+				$media->uri(array('file' => 'css/print.css'))  => 'print',
+				$media->uri(array('file' => 'css/screen.css')) => 'screen',
+				$media->uri(array('file' => 'css/kodoc.css'))  => 'screen',
+				$media->uri(array('file' => 'css/shCore.css')) => 'screen',
+				$media->uri(array('file' => 'css/shThemeKodoc.css')) => 'screen',
+			);
+
+			// Add scripts
+			$this->template->scripts = array(
+				$media->uri(array('file' => 'js/jquery.min.js')),
+				$media->uri(array('file' => 'js/jquery.cookie.js')),
+				$media->uri(array('file' => 'js/kodoc.js')),
+				// Syntax Highlighter
+				$media->uri(array('file' => 'js/shCore.js')),
+				$media->uri(array('file' => 'js/shBrushPhp.js')),
+			);
+
+			// Add languages
+			$this->template->translations = Kohana::message('userguide', 'translations');
+		}
+
+		return parent::after();
+	}
+
+	public function file($page)
+	{
+		return Kohana::find_file('guide', $page, 'md');
+	}
+
+	public function section($page)
+	{
+		$markdown = $this->_get_all_menu_markdown();
+		
+		if (preg_match('~\*{2}(.+?)\*{2}[^*]+\[[^\]]+\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
+		{
+			return $matches[1];
+		}
+		
+		return $page;
+	}
+
+	public function title($page)
+	{
+		$markdown = $this->_get_all_menu_markdown();
+		
+		if (preg_match('~\[([^\]]+)\]\('.preg_quote($page).'\)~mu', $markdown, $matches))
+		{
+			// Found a title for this link
+			return $matches[1];
+		}
+		
+		return $page;
+	}
+	
+	protected function _get_all_menu_markdown()
+	{
+		// Only do this once per request...
+		static $markdown = '';
+		
+		if (empty($markdown))
+		{
+			// Get menu items
+			$file = $this->file($this->request->param('module').'/menu');
+	
+			if ($file AND $text = file_get_contents($file))
+			{
+				// Add spans around non-link categories. This is a terrible hack.
+				//echo Kohana::debug($text);
+				
+				//$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1<span>$2</span>',$text);
+				$text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1<span>$2</span>',$text);
+				//echo Kohana::debug($text);
+				$markdown .= $text;
+			}
+			
+		}
+		
+		return $markdown;
+	}
+	
+	// Get the list of modules from the config, and reverses it so it displays in the order the modules are added, but move Kohana to the top.
+	protected function _modules()
+	{
+		$modules = array_reverse(Kohana::config('userguide.modules'));
+		
+		if (isset($modules['kohana']))
+		{
+			$kohana = $modules['kohana'];
+			unset($modules['kohana']);
+			$modules = array_merge(array('kohana' => $kohana), $modules);
+		}
+		
+		// Remove modules that have been disabled via config
+		foreach ($modules as $key => $value)
+		{
+			if ( ! Kohana::config('userguide.modules.'.$key.'.enabled'))
+			{
+				unset($modules[$key]);
+			}
+		}
+		
+		return $modules;
+	}
+
+} // End Userguide

includes/kohana/modules/userguide/classes/kodoc.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc extends Kohana_Kodoc {}

includes/kohana/modules/userguide/classes/kodoc/class.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc_Class extends Kohana_Kodoc_Class {}

includes/kohana/modules/userguide/classes/kodoc/markdown.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc_Markdown extends Kohana_Kodoc_Markdown {}

includes/kohana/modules/userguide/classes/kodoc/method.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc_Method extends Kohana_Kodoc_Method {} 

includes/kohana/modules/userguide/classes/kodoc/method/param.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc_Method_Param extends Kohana_Kodoc_Method_Param {}

includes/kohana/modules/userguide/classes/kodoc/missing.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+abstract class Kodoc_Missing extends Kohana_Kodoc_Missing {  }

includes/kohana/modules/userguide/classes/kodoc/property.php

@@ -0,0 +1,3 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+
+class Kodoc_Property extends Kohana_Kodoc_Property {}

includes/kohana/modules/userguide/classes/kohana/kodoc.php

@@ -0,0 +1,354 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Documentation generator.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2008-2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc {
+
+	/**
+	 * @var string  PCRE fragment for matching 'Class', 'Class::method', 'Class::method()' or 'Class::$property'
+	 */
+	public static $regex_class_member = '((\w++)(?:::(\$?\w++))?(?:\(\))?)';
+
+	/**
+	 * Make a class#member API link using an array of matches from [Kodoc::$regex_class_member]
+	 *
+	 * @param   array   $matches    array( 1 => link text, 2 => class name, [3 => member name] )
+	 * @return  string
+	 */
+	public static function link_class_member($matches)
+	{
+		$link = $matches[1];
+		$class = $matches[2];
+		$member = NULL;
+
+		if (isset($matches[3]))
+		{
+			// If the first char is a $ it is a property, e.g. Kohana::$base_url
+			if ($matches[3][0] === '$')
+			{
+				$member = '#property:'.substr($matches[3], 1);
+			}
+			else
+			{
+				$member = '#'.$matches[3];
+			}
+		}
+
+		return HTML::anchor(Route::get('docs/api')->uri(array('class' => $class)).$member, $link);
+	}
+
+	public static function factory($class)
+	{
+		return new Kodoc_Class($class);
+	}
+
+	/**
+	 * Creates an html list of all classes sorted by category (or package if no category)
+	 *
+	 * @return   string   the html for the menu
+	 */
+	public static function menu()
+	{
+		$classes = Kodoc::classes();
+
+		foreach ($classes as $class)
+		{
+			if (isset($classes['kohana_'.$class]))
+			{
+				// Remove extended classes
+				unset($classes['kohana_'.$class]);
+			}
+		}
+
+		ksort($classes);
+
+		$menu = array();
+
+		$route = Route::get('docs/api');
+
+		foreach ($classes as $class)
+		{
+			$class = Kodoc_Class::factory($class);
+
+			// Test if we should show this class
+			if ( ! Kodoc::show_class($class))
+				continue;
+
+			$link = HTML::anchor($route->uri(array('class' => $class->class->name)), $class->class->name);
+
+			if (isset($class->tags['package']))
+			{
+				foreach ($class->tags['package'] as $package)
+				{
+					if (isset($class->tags['category']))
+					{
+						foreach ($class->tags['category'] as $category)
+						{
+							$menu[$package][$category][] = $link;
+						}
+					}
+					else
+					{
+						$menu[$package]['Base'][] = $link;
+					}
+				}
+			}
+			else
+			{
+				$menu['[Unknown]']['Base'][] = $link;
+			}
+		}
+
+		// Sort the packages
+		ksort($menu);
+
+		return View::factory('userguide/api/menu')
+			->bind('menu', $menu);
+	}
+
+	/**
+	 * Returns an array of all the classes available, built by listing all files in the classes folder and then trying to create that class.
+	 *
+	 * This means any empty class files (as in complety empty) will cause an exception
+	 *
+	 * @param   array   array of files, obtained using Kohana::list_files
+	 * @return  array   an array of all the class names
+	 */
+	public static function classes(array $list = NULL)
+	{
+		if ($list === NULL)
+		{
+			$list = Kohana::list_files('classes');
+		}
+
+		$classes = array();
+
+		foreach ($list as $name => $path)
+		{
+			if (is_array($path))
+			{
+				$classes += Kodoc::classes($path);
+			}
+			else
+			{
+				// Remove "classes/" and the extension
+				$class = substr($name, 8, -(strlen(EXT)));
+
+				// Convert slashes to underscores
+				$class = str_replace(DIRECTORY_SEPARATOR, '_', strtolower($class));
+
+				$classes[$class] = $class;
+			}
+		}
+
+		return $classes;
+	}
+
+	/**
+	 * Get all classes and methods of files in a list.
+	 *
+	 * >  I personally don't like this as it was used on the index page.  Way too much stuff on one page.  It has potential for a package index page though.
+	 * >  For example:  class_methods( Kohana::list_files('classes/sprig') ) could make a nice index page for the sprig package in the api browser
+	 * >     ~bluehawk
+	 *
+	 */
+	public static function class_methods(array $list = NULL)
+	{
+		$list = Kodoc::classes($list);
+
+		$classes = array();
+
+		foreach ($list as $class)
+		{
+			$_class = new ReflectionClass($class);
+
+			if (stripos($_class->name, 'Kohana_') === 0)
+			{
+				// Skip transparent extension classes
+				continue;
+			}
+
+			$methods = array();
+
+			foreach ($_class->getMethods() as $_method)
+			{
+				$declares = $_method->getDeclaringClass()->name;
+
+				if (stripos($declares, 'Kohana_') === 0)
+				{
+					// Remove "Kohana_"
+					$declares = substr($declares, 7);
+				}
+
+				if ($declares === $_class->name OR $declares === "Core")
+				{
+					$methods[] = $_method->name;
+				}
+			}
+
+			sort($methods);
+
+			$classes[$_class->name] = $methods;
+		}
+
+		return $classes;
+	}
+
+	/**
+	 * Parse a comment to extract the description and the tags
+	 *
+	 * @param   string  the comment retreived using ReflectionClass->getDocComment()
+	 * @return  array   array(string $description, array $tags)
+	 */
+	public static function parse($comment)
+	{
+		// Normalize all new lines to \n
+		$comment = str_replace(array("\r\n", "\n"), "\n", $comment);
+
+		// Remove the phpdoc open/close tags and split
+		$comment = array_slice(explode("\n", $comment), 1, -1);
+
+		// Tag content
+		$tags = array();
+
+		foreach ($comment as $i => $line)
+		{
+			// Remove all leading whitespace
+			$line = preg_replace('/^\s*\* ?/m', '', $line);
+
+			// Search this line for a tag
+			if (preg_match('/^@(\S+)(?:\s*(.+))?$/', $line, $matches))
+			{
+				// This is a tag line
+				unset($comment[$i]);
+
+				$name = $matches[1];
+				$text = isset($matches[2]) ? $matches[2] : '';
+
+				switch ($name)
+				{
+					case 'license':
+						if (strpos($text, '://') !== FALSE)
+						{
+							// Convert the lincense into a link
+							$text = HTML::anchor($text);
+						}
+					break;
+					case 'link':
+						$text = preg_split('/\s+/', $text, 2);
+						$text = HTML::anchor($text[0], isset($text[1]) ? $text[1] : $text[0]);
+					break;
+					case 'copyright':
+						if (strpos($text, '(c)') !== FALSE)
+						{
+							// Convert the copyright sign
+							$text = str_replace('(c)', '&copy;', $text);
+						}
+					break;
+					case 'throws':
+						if (preg_match('/^(\w+)\W(.*)$/', $text, $matches))
+						{
+							$text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $matches[1])), $matches[1]).' '.$matches[2];
+						}
+						else
+						{
+							$text = HTML::anchor(Route::get('docs/api')->uri(array('class' => $text)), $text);
+						}
+					break;
+					case 'uses':
+						if (preg_match('/^'.Kodoc::$regex_class_member.'$/i', $text, $matches))
+						{
+							$text = Kodoc::link_class_member($matches);
+						}
+					break;
+					// Don't show @access lines, they are shown elsewhere
+					case 'access':
+						continue 2;
+				}
+
+				// Add the tag
+				$tags[$name][] = $text;
+			}
+			else
+			{
+				// Overwrite the comment line
+				$comment[$i] = (string) $line;
+			}
+		}
+
+		// Concat the comment lines back to a block of text
+		if ($comment = trim(implode("\n", $comment)))
+		{
+			// Parse the comment with Markdown
+			$comment = Markdown($comment);
+		}
+
+		return array($comment, $tags);
+	}
+
+	/**
+	 * Get the source of a function
+	 *
+	 * @param  string   the filename
+	 * @param  int      start line?
+	 * @param  int      end line?
+	 */
+	public static function source($file, $start, $end)
+	{
+		if ( ! $file) return FALSE;
+
+		$file = file($file, FILE_IGNORE_NEW_LINES);
+
+		$file = array_slice($file, $start - 1, $end - $start + 1);
+
+		if (preg_match('/^(\s+)/', $file[0], $matches))
+		{
+			$padding = strlen($matches[1]);
+
+			foreach ($file as & $line)
+			{
+				$line = substr($line, $padding);
+			}
+		}
+
+		return implode("\n", $file);
+	}
+
+	/**
+	 * Test whether a class should be shown, based on the api_packages config option
+	 *
+	 * @param  Kodoc_Class  the class to test
+	 * @return  bool  whether this class should be shown
+	 */
+	public static function show_class(Kodoc_Class $class)
+	{
+		$api_packages = Kohana::config('userguide.api_packages');
+
+		// If api_packages is true, all packages should be shown
+		if ($api_packages === TRUE)
+			return TRUE;
+
+		// Get the package tags for this class (as an array)
+		$packages = Arr::get($class->tags, 'package', array('None'));
+
+		$show_this = FALSE;
+
+		// Loop through each package tag
+		foreach ($packages as $package)
+		{
+			// If this package is in the allowed packages, set show this to true
+			if (in_array($package, explode(',', $api_packages)))
+				$show_this = TRUE;
+		}
+
+		return $show_this;
+	}
+
+
+} // End Kodoc

includes/kohana/modules/userguide/classes/kohana/kodoc/class.php

@@ -0,0 +1,216 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Class documentation generator.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc_Class extends Kodoc {
+
+	/**
+	 * @var  ReflectionClass The ReflectionClass for this class
+	 */
+	public $class;
+
+	/**
+	 * @var  string  modifiers like abstract, final
+	 */
+	public $modifiers;
+
+	/**
+	 * @var  string  description of the class from the comment
+	 */
+	public $description;
+
+	/**
+	 * @var  array  array of tags, retrieved from the comment
+	 */
+	public $tags = array();
+
+	/**
+	 * @var  array  array of this classes constants
+	 */
+	public $constants = array();
+
+	/**
+	 * Loads a class and uses [reflection](http://php.net/reflection) to parse
+	 * the class. Reads the class modifiers, constants and comment. Parses the
+	 * comment to find the description and tags.
+	 *
+	 * @param   string   class name
+	 * @return  void
+	 */
+	public function __construct($class)
+	{
+		$this->class = new ReflectionClass($class);
+
+		if ($modifiers = $this->class->getModifiers())
+		{
+			$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
+		}
+
+		if ($constants = $this->class->getConstants())
+		{
+			foreach ($constants as $name => $value)
+			{
+				$this->constants[$name] = Kohana::debug($value);
+			}
+		}
+
+		$parent = $this->class;
+
+		do
+		{
+			if ($comment = $parent->getDocComment())
+			{
+				// Found a description for this class
+				break;
+			}
+		}
+		while ($parent = $parent->getParentClass());
+
+		list($this->description, $this->tags) = Kodoc::parse($comment);
+		
+		// If this class extends Kodoc_Missing, add a warning about possible
+		// incomplete documentation
+		$parent = $this->class;
+		
+		while ($parent = $parent->getParentClass())
+		{
+			if ($parent->name == 'Kodoc_Missing')
+			{
+				$warning = "[!!] **This class, or a class parent, could not be
+				           found or loaded. This could be caused by a missing
+						   module or other dependancy. The documentation for
+						   class may not be complete!**";
+				$this->description = Markdown($warning).$this->description;
+			}
+		}
+	}
+
+	/**
+	 * Gets a list of the class properties as [Kodoc_Property] objects.
+	 *
+	 * @return  array
+	 */
+	public function properties()
+	{
+		$props = $this->class->getProperties();
+
+		usort($props, array($this,'_prop_sort'));
+
+		foreach ($props as $key => $property)
+		{
+			// Create Kodoc Properties for each property
+			$props[$key] = new Kodoc_Property($this->class->name, $property->name);
+		}
+
+		return $props;
+	}
+	
+	protected function _prop_sort($a, $b)
+	{
+		// If one property is public, and the other is not, it goes on top
+		if ($a->isPublic() AND ( ! $b->isPublic()))
+			return -1;
+		if ($b->isPublic() AND ( ! $a->isPublic()))
+			return 1;
+		
+		// If one property is protected and the other is private, it goes on top
+		if ($a->isProtected() AND $b->isPrivate())
+			return -1;
+		if ($b->isProtected() AND $a->isPrivate())
+			return 1;
+		
+		// Otherwise just do alphabetical
+		return strcmp($a->name, $b->name);
+	}
+
+	/**
+	 * Gets a list of the class properties as [Kodoc_Method] objects.
+	 *
+	 * @return  array
+	 */
+	public function methods()
+	{
+		$methods = $this->class->getMethods();
+
+		usort($methods, array($this,'_method_sort'));
+
+		foreach ($methods as $key => $method)
+		{
+			$methods[$key] = new Kodoc_Method($this->class->name, $method->name);
+		}
+
+		return $methods;
+	}
+	
+	/**
+	 * Sort methods based on their visibility and declaring class based on:
+	 *  - methods will be sorted public, protected, then private.
+	 *  - methods that are declared by an ancestor will be after classes
+	 *    declared by the current class
+	 *  - lastly, they will be sorted alphabetically
+	 * 
+	 */
+	protected function _method_sort($a, $b)
+	{
+		// If one method is public, and the other is not, it goes on top
+		if ($a->isPublic() AND ( ! $b->isPublic()))
+			return -1;
+		if ($b->isPublic() AND ( ! $a->isPublic()))
+			return 1;
+		
+		// If one method is protected and the other is private, it goes on top
+		if ($a->isProtected() AND $b->isPrivate())
+			return -1;
+		if ($b->isProtected() AND $a->isPrivate())
+			return 1;
+		
+		// The methods have the same visibility, so check the declaring class depth:
+		
+		
+		/*
+		echo kohana::debug('a is '.$a->class.'::'.$a->name,'b is '.$b->class.'::'.$b->name,
+						   'are the classes the same?', $a->class == $b->class,'if they are, the result is:',strcmp($a->name, $b->name),
+						   'is a this class?', $a->name == $this->class->name,-1,
+						   'is b this class?', $b->name == $this->class->name,1,
+						   'otherwise, the result is:',strcmp($a->class, $b->class)
+						   );
+		*/
+
+		// If both methods are defined in the same class, just compare the method names
+		if ($a->class == $b->class)
+			return strcmp($a->name, $b->name);
+
+		// If one of them was declared by this class, it needs to be on top
+		if ($a->name == $this->class->name)
+			return -1;
+		if ($b->name == $this->class->name)
+			return 1;
+
+		// Otherwise, get the parents of each methods declaring class, then compare which function has more "ancestors"
+		$adepth = 0;
+		$bdepth = 0;
+
+		$parent = $a->getDeclaringClass();
+		do
+		{
+			$adepth++;
+		}
+		while ($parent = $parent->getParentClass());
+
+		$parent = $b->getDeclaringClass();
+		do
+		{
+			$bdepth++;
+		}
+		while ($parent = $parent->getParentClass());
+
+		return $bdepth - $adepth;
+	}
+
+} // End Kodac_Class

includes/kohana/modules/userguide/classes/kohana/kodoc/markdown.php

@@ -0,0 +1,264 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Custom Markdown parser for Kohana documentation.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser {
+
+	/**
+	 * @var  string  base url for links
+	 */
+	public static $base_url = '';
+
+	/**
+	 * @var  string  base url for images
+	 */
+	public static $image_url = '';
+	
+	/**
+	 * Currently defined heading ids.  
+	 * Used to prevent creating multiple headings with same id.
+	 * @var array
+	 */
+	protected $_heading_ids = array();
+	
+	/**
+	 * @var  string   the generated table of contents
+	 */
+	protected static $_toc = "";
+	
+	/**
+	 * Slightly less terrible way to make it so the TOC only shows up when we
+	 * want it to.  set this to true to show the toc.
+	 */
+	public static $show_toc = false;
+	
+	public function __construct()
+	{
+		// doImage is 10, add image url just before
+		$this->span_gamut['doImageURL'] = 9;
+
+		// doLink is 20, add base url just before
+		$this->span_gamut['doBaseURL'] = 19;
+
+		// Add API links
+		$this->span_gamut['doAPI'] = 90;
+
+		// Add note spans last
+		$this->span_gamut['doNotes'] = 100;
+
+		// Parse Kohana view inclusions at the very end
+		$this->document_gamut['doIncludeViews'] = 99;
+
+		// Show table of contents for userguide pages
+		$this->document_gamut['doTOC'] = 100;
+
+		// PHP4 makes me sad.
+		parent::MarkdownExtra_Parser();
+	}
+	
+	/**
+	 * Callback for the heading setext style
+	 * 
+	 * Heading 1
+	 * =========
+	 *
+	 * @param  array    Matches from regex call
+	 * @return string   Generated html
+	 */
+	function _doHeaders_callback_setext($matches) 
+	{
+		if ($matches[3] == '-' && preg_match('{^- }', $matches[1]))
+			return $matches[0];
+		$level = $matches[3]{0} == '=' ? 1 : 2;
+		$attr  = $this->_doHeaders_attr($id =& $matches[2]);
+		
+		// Only auto-generate id if one doesn't exist
+		if(empty($attr))
+			$attr = ' id="'.$this->make_heading_id($matches[1]).'"';
+		
+		// Add this header to the page toc
+		$this->_add_to_toc($level,$matches[1],$this->make_heading_id($matches[1]));
+		
+		$block = "<h$level$attr>".$this->runSpanGamut($matches[1])."</h$level>";
+		return "\n" . $this->hashBlock($block) . "\n\n";
+	}
+	
+	/**
+	 * Callback for the heading atx style
+	 *
+	 * # Heading 1
+	 *
+	 * @param  array    Matches from regex call
+	 * @return string   Generated html
+	 */
+	function _doHeaders_callback_atx($matches) 
+	{
+		$level = strlen($matches[1]);
+		$attr  = $this->_doHeaders_attr($id =& $matches[3]);
+		
+		// Only auto-generate id if one doesn't exist
+		if(empty($attr))
+			$attr = ' id="'.$this->make_heading_id($matches[2]).'"';
+		
+		// Add this header to the page toc
+		$this->_add_to_toc($level,$matches[2],$this->make_heading_id($matches[2]));
+		
+		$block = "<h$level$attr>".$this->runSpanGamut($matches[2])."</h$level>";
+		return "\n" . $this->hashBlock($block) . "\n\n";
+	}
+
+	
+	/**
+	 * Makes a heading id from the heading text
+	 * If any heading share the same name then subsequent headings will have an integer appended
+	 *
+	 * @param  string The heading text
+	 * @return string ID for the heading
+	 */
+	function make_heading_id($heading)
+	{
+		$id = url::title($heading, '-', TRUE);
+		
+		if(isset($this->_heading_ids[$id]))
+		{
+			$id .= '-';
+			
+			$count = 0;
+			
+			while (isset($this->_heading_ids[$id]) AND ++$count)
+			{
+				$id .= $count;
+			}
+		}		
+		
+		return $id;
+	}
+
+	public function doIncludeViews($text)
+	{
+		if (preg_match_all('/{{([^\s{}]++)}}/', $text, $matches, PREG_SET_ORDER))
+		{
+			$replace = array();
+
+			$replace = array();
+
+			foreach ($matches as $set)
+			{
+				list($search, $view) = $set;
+
+				try
+				{
+					$replace[$search] = View::factory($view)->render();
+				}
+				catch (Exception $e)
+				{
+					ob_start();
+
+					// Capture the exception handler output and insert it instead
+					Kohana::exception_handler($e);
+
+					$replace[$search] = ob_get_clean();
+				}
+			}
+
+			$text = strtr($text, $replace);
+		}
+
+		return $text;
+	}
+
+	/**
+	 * Add the current base url to all local links.
+	 *
+	 *     [filesystem](about.filesystem "Optional title")
+	 *
+	 * @param   string  span text
+	 * @return  string
+	 */
+	public function doBaseURL($text)
+	{
+		// URLs containing "://" are left untouched
+		return preg_replace('~(?<!!)(\[.+?\]\()(?!\w++://)(?!#)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$base_url.'$2', $text);
+	}
+
+	/**
+	 * Add the current base url to all local images.
+	 *
+	 *     ![Install Page](img/install.png "Optional title")
+	 *
+	 * @param   string  span text
+	 * @return  string
+	 */
+	public function doImageURL($text)
+	{
+		// URLs containing "://" are left untouched
+		return preg_replace('~(!\[.+?\]\()(?!\w++://)(\S*(?:\s*+".+?")?\))~', '$1'.Kodoc_Markdown::$image_url.'$2', $text);
+	}
+
+	/**
+	 * Parses links to the API browser.
+	 *
+	 *     [Class_Name], [Class::method] or [Class::$property]
+	 *
+	 * @param   string   span text
+	 * @return  string
+	 */
+	public function doAPI($text)
+	{
+		return preg_replace_callback('/\['.Kodoc::$regex_class_member.'\]/i', 'Kodoc::link_class_member', $text);
+	}
+
+	/**
+	 * Wrap notes in the applicable markup. Notes can contain single newlines.
+	 *
+	 *     [!!] Remember the milk!
+	 *
+	 * @param   string  span text
+	 * @return  string
+	 */
+	public function doNotes($text)
+	{
+		if ( ! preg_match('/^\[!!\]\s*+(.+?)(?=\n{2,}|$)/s', $text, $match))
+		{
+			return $text;
+		}
+
+		return $this->hashBlock('<p class="note">'.$match[1].'</p>');
+	}
+	
+	protected function _add_to_toc($level, $name, $id)
+	{
+		self::$_toc[] = array(
+			'level' => $level,
+			'name'  => $name,
+			'id'    => $id);
+	}
+	
+	public function doTOC($text)
+	{
+		// Only add the toc do userguide pages, not api since they already have one
+		if (self::$show_toc AND Route::name(Request::instance()->route) == "docs/guide")
+		{
+			$toc = View::factory('userguide/page-toc')
+				->set('array', self::$_toc)
+				->render()
+				;
+
+			if (($offset = strpos($text, '<p>')) !== FALSE)
+			{
+				// Insert the page TOC just before the first <p>, which every
+				// Markdown page should (will?) have.
+				$text = substr_replace($text, $toc, $offset, 0);
+			}
+		}
+
+		return $text;
+	}
+
+} // End Kodoc_Markdown

includes/kohana/modules/userguide/classes/kohana/kodoc/method.php

@@ -0,0 +1,141 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Class method documentation generator.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc_Method extends Kodoc {
+
+	/**
+	 * @var  ReflectionMethod   The ReflectionMethod for this class
+	 */
+	public $method;
+
+	/**
+	 * @var  array    array of Kodoc_Method_Param
+	 */
+	public $params;
+
+	/**
+	 * @var  array   the things this function can return
+	 */
+	public $return = array();
+
+	/**
+	 * @var  string  the source code for this function
+	 */
+	public $source;
+
+	public function __construct($class, $method)
+	{
+		$this->method = new ReflectionMethod($class, $method);
+
+		$this->class = $parent = $this->method->getDeclaringClass();
+
+		if ($modifiers = $this->method->getModifiers())
+		{
+			$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
+		}
+
+		do
+		{
+			if ($parent->hasMethod($method) AND $comment = $parent->getMethod($method)->getDocComment())
+			{
+				// Found a description for this method
+				break;
+			}
+		}
+		while ($parent = $parent->getParentClass());
+
+		list($this->description, $tags) = Kodoc::parse($comment);
+
+		if ($file = $this->class->getFileName())
+		{
+			$this->source = Kodoc::source($file, $this->method->getStartLine(), $this->method->getEndLine());
+		}
+
+		if (isset($tags['param']))
+		{
+			$params = array();
+
+			foreach ($this->method->getParameters() as $i => $param)
+			{
+				$param = new Kodoc_Method_Param(array($this->method->class, $this->method->name),$i);
+
+				if (isset($tags['param'][$i]))
+				{
+					preg_match('/^(\S+)(?:\s*(?:\$'.$param->name.'\s*)?(.+))?$/', $tags['param'][$i], $matches);
+
+					$param->type = $matches[1];
+
+					if (isset($matches[2]))
+					{
+						$param->description = ucfirst($matches[2]);
+					}
+				}
+				$params[] = $param;
+			}
+
+			$this->params = $params;
+
+			unset($tags['param']);
+		}
+
+		if (isset($tags['return']))
+		{
+			foreach ($tags['return'] as $return)
+			{
+				if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $return, $matches))
+				{
+					$this->return[] = array($matches[1], isset($matches[2]) ? $matches[2] : '');
+				}
+			}
+
+			unset($tags['return']);
+		}
+
+		$this->tags = $tags;
+	}
+
+	public function params_short()
+	{
+		$out = '';
+		$required = TRUE;
+		$first = TRUE;
+		foreach ($this->params as $param)
+		{
+			if ($required AND $param->default AND $first)
+			{
+				$out .= '[ '.$param;
+				$required = FALSE;
+				$first = FALSE;
+			}
+			elseif ($required AND $param->default)
+			{
+				$out .= '[, '.$param;
+				$required = FALSE;
+			}
+			elseif ($first)
+			{
+				$out .= $param;
+				$first = FALSE;
+			}
+			else
+			{
+				$out .= ', '.$param;
+			}
+		}
+
+		if ( ! $required)
+		{
+			$out .= '] ';
+		}
+
+		return $out;
+	}
+
+} // End Kodoc_Method

includes/kohana/modules/userguide/classes/kohana/kodoc/method/param.php

@@ -0,0 +1,101 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Class method parameter documentation generator.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc_Method_Param extends Kodoc {
+
+	/**
+	 * @var  object  ReflectionParameter for this property
+	 */
+	public $param;
+
+	/**
+	 * @var  string  name of this var
+	 */
+	public $name;
+
+	/**
+	 * @var  string  variable type, retrieved from the comment
+	 */
+	public $type;
+
+	/**
+	 * @var  string  default value of this param
+	 */
+	public $default;
+
+	/**
+	 * @var  string  description of this parameter
+	 */
+	public $description;
+
+	/**
+	 * @var  boolean  is the parameter passed by reference?
+	 */
+	public $reference = FALSE;
+
+	/**
+	 * @var  boolean  is the parameter optional?
+	 */
+	public $optional = FALSE;
+
+	public function __construct($method, $param)
+	{
+		$this->param = new ReflectionParameter($method, $param);
+
+		$this->name = $this->param->name;
+
+		if ($this->param->isDefaultValueAvailable())
+		{
+			$this->default = Kohana::dump($this->param->getDefaultValue());
+		}
+
+		if ($this->param->isPassedByReference())
+		{
+			$this->reference = TRUE;
+		}
+
+		if ($this->param->isOptional())
+		{
+			$this->optional = TRUE;
+		}
+	}
+
+	public function __toString()
+	{
+		$display = '';
+
+		if ($this->type)
+		{
+			$display .= '<small>'.$this->type.'</small> ';
+		}
+
+		if ($this->reference)
+		{
+			$display .= '<small><abbr title="passed by reference">&</abbr></small> ';
+		}
+
+		if ($this->description)
+		{
+			$display .= '<span class="param" title="'.$this->description.'">$'.$this->name.'</span> ';
+		}
+		else
+		{
+			$display .= '$'.$this->name.' ';
+		}
+
+		if ($this->default)
+		{
+			$display .= '<small>= '.$this->default.'</small> ';
+		}
+
+		return $display;
+	}
+
+} // End Kodoc_Method_Param

includes/kohana/modules/userguide/classes/kohana/kodoc/missing.php

@@ -0,0 +1,36 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Set Kodoc_Missing::create_class as an autoloading to prevent missing classes
+ * from crashing the api browser.  Classes that are missing a parent will
+ * extend this class, and get a warning in the API browser.
+ *
+ * @package    Kohana/Userguide
+ * @category   Undocumented
+ * @author     Kohana Team
+ * @since      3.0.7
+ */
+abstract class Kohana_Kodoc_Missing {
+
+	/**
+	 * Creates classes when they are otherwise not found.
+	 *
+	 *     Kodoc::create_class('ThisClassDoesNotExist');
+	 *
+	 * [!!] All classes created will extend [Kodoc_Missing].
+	 *
+	 * @param   string   class name
+	 * @return  boolean
+	 * @since   3.0.7
+	 */
+	public static function create_class($class)
+	{
+		if ( ! class_exists($class))
+		{
+			// Create a new missing class
+			eval("class {$class} extends Kodoc_Missing {}");
+		}
+
+		return TRUE;
+	}
+
+} // End Kohana_Kodoc_Missing

includes/kohana/modules/userguide/classes/kohana/kodoc/property.php

@@ -0,0 +1,83 @@
+<?php defined('SYSPATH') or die('No direct script access.');
+/**
+ * Class property documentation generator.
+ *
+ * @package    Kohana/Userguide
+ * @category   Base
+ * @author     Kohana Team
+ * @copyright  (c) 2009 Kohana Team
+ * @license    http://kohanaphp.com/license
+ */
+class Kohana_Kodoc_Property extends Kodoc {
+
+	/**
+	 * @var  object  ReflectionProperty
+	 */
+	public $property;
+
+	/**
+	 * @var  string   modifiers: public, private, static, etc
+	 */
+	public $modifiers = 'public';
+
+	/**
+	 * @var  string  variable type, retrieved from the comment
+	 */
+	public $type;
+
+	/**
+	 * @var  string  value of the property
+	 */
+	public $value;
+
+	public function __construct($class, $property)
+	{
+		$property = new ReflectionProperty($class, $property);
+
+		list($description, $tags) = Kodoc::parse($property->getDocComment());
+
+		$this->description = $description;
+
+		if ($modifiers = $property->getModifiers())
+		{
+			$this->modifiers = '<small>'.implode(' ', Reflection::getModifierNames($modifiers)).'</small> ';
+		}
+
+		if (isset($tags['var']))
+		{
+			if (preg_match('/^(\S*)(?:\s*(.+?))?$/', $tags['var'][0], $matches))
+			{
+				$this->type = $matches[1];
+
+				if (isset($matches[2]))
+				{
+					$this->description = Markdown($matches[2]);
+				}
+			}
+		}
+
+		$this->property = $property;
+		
+		// Show the value of static properties, but only if they are public or we are php 5.3 or higher and can force them to be accessible
+		if ($property->isStatic() AND ($property->isPublic() OR version_compare(PHP_VERSION, '5.3', '>=')))
+		{
+			// Force the property to be accessible
+			if (version_compare(PHP_VERSION, '5.3', '>='))
+			{
+				$property->setAccessible(TRUE);
+			}
+			
+			// Don't debug the entire object, just say what kind of object it is
+			if (is_object($property->getValue($class)))
+			{
+				$this->value = '<pre>object '.get_class($property->getValue($class)).'()</pre>';
+			}
+			else
+			{
+				$this->value = Kohana::debug($property->getValue($class));
+			}
+		}
+		
+	}
+
+} // End Kodoc_Property