From 52a78dcc45514cf998d643196699cce0aed04e78 Mon Sep 17 00:00:00 2001 From: Chris Bandy Date: Tue, 28 Feb 2012 09:05:58 -0600 Subject: [PATCH 01/12] PHPCS: Cleanup whitespace, constants and braces --- classes/Controller/Userguide.php | 18 ++++++++---------- classes/Kohana/Kodoc.php | 4 ++-- classes/Kohana/Kodoc/Markdown.php | 20 ++++++++++++-------- 3 files changed, 22 insertions(+), 20 deletions(-) diff --git a/classes/Controller/Userguide.php b/classes/Controller/Userguide.php index a23fa8b0..55298a2f 100644 --- a/classes/Controller/Userguide.php +++ b/classes/Controller/Userguide.php @@ -73,7 +73,7 @@ public function error($message) ); } // 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') + elseif (Route::name($this->request->route()) == 'docs/api') { $this->template->menu = Kodoc::menu(); @@ -113,13 +113,13 @@ public function action_docs() } // Prevent "guide/module" and "guide/module/index" from having duplicate content - if ( $page == 'index') + 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 ) + if ( ! $page) { $page = 'index'; } @@ -138,12 +138,14 @@ public function action_docs() Kodoc_Markdown::$image_url = URL::site($this->media->uri()).'/'.$module.'/'; // Set the page title - $this->template->title = $page == 'index' ? Kohana::$config->load('userguide.modules.'.$module.'.name') : $this->title($page); + $this->template->title = ($page == 'index') + ? Kohana::$config->load('userguide.modules.'.$module.'.name') + : $this->title($page); // Parse the page contents into the template - Kodoc_Markdown::$show_toc = true; + Kodoc_Markdown::$show_toc = TRUE; $this->template->content = Kodoc_Markdown::markdown(file_get_contents($file)); - Kodoc_Markdown::$show_toc = false; + Kodoc_Markdown::$show_toc = FALSE; // Attach this module's menu to the template $this->template->menu = Kodoc_Markdown::markdown($this->_get_all_menu_markdown()); @@ -333,11 +335,7 @@ protected function _get_all_menu_markdown() 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$2',$text); $text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1$2',$text); - //echo Kohana::debug($text); $markdown .= $text; } diff --git a/classes/Kohana/Kodoc.php b/classes/Kohana/Kodoc.php index acd9cbcf..e808668d 100644 --- a/classes/Kohana/Kodoc.php +++ b/classes/Kohana/Kodoc.php @@ -275,7 +275,7 @@ public static function parse($comment, $html = TRUE) * @param string $text Content of the tag * @return void */ - $add_tag = function($tag, $text) use ($html, &$tags) + $add_tag = function ($tag, $text) use ($html, & $tags) { // Don't show @access lines, they are shown elsewhere if ($tag !== 'access') @@ -290,7 +290,7 @@ public static function parse($comment, $html = TRUE) } }; - $comment = $tag = null; + $comment = $tag = NULL; $end = count($lines[1]) - 1; foreach ($lines[1] as $i => $line) diff --git a/classes/Kohana/Kodoc/Markdown.php b/classes/Kohana/Kodoc/Markdown.php index 549b24b7..99876448 100644 --- a/classes/Kohana/Kodoc/Markdown.php +++ b/classes/Kohana/Kodoc/Markdown.php @@ -36,7 +36,7 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * 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 static $show_toc = FALSE; /** * Transform some text using [Kodoc_Markdown] @@ -93,20 +93,22 @@ public function __construct() */ function _doHeaders_callback_setext($matches) { - if ($matches[3] == '-' && preg_match('{^- }', $matches[1])) + if ($matches[3] == '-' AND preg_match('{^- }', $matches[1])) return $matches[0]; - $level = $matches[3]{0} == '=' ? 1 : 2; + $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)) + 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 = "".$this->runSpanGamut($matches[1]).""; - return "\n" . $this->hashBlock($block) . "\n\n"; + return "\n".$this->hashBlock($block)."\n\n"; } /** @@ -123,14 +125,16 @@ function _doHeaders_callback_atx($matches) $attr = $this->_doHeaders_attr($id =& $matches[3]); // Only auto-generate id if one doesn't exist - if(empty($attr)) + 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 = "".$this->runSpanGamut($matches[2]).""; - return "\n" . $this->hashBlock($block) . "\n\n"; + return "\n".$this->hashBlock($block)."\n\n"; } @@ -145,7 +149,7 @@ function make_heading_id($heading) { $id = url::title($heading, '-', TRUE); - if(isset($this->_heading_ids[$id])) + if (isset($this->_heading_ids[$id])) { $id .= '-'; From 78bc8b160bbbf4fdcbe2bc92403bb2011b8a43df Mon Sep 17 00:00:00 2001 From: Soon Van Date: Wed, 30 May 2012 00:06:47 -0400 Subject: [PATCH 02/12] structure flow in doc and sentences; reduce sidescroll in code --- guide/userguide/adding.md | 58 ++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 19 deletions(-) diff --git a/guide/userguide/adding.md b/guide/userguide/adding.md index 156eca82..cd12fe71 100644 --- a/guide/userguide/adding.md +++ b/guide/userguide/adding.md @@ -1,38 +1,42 @@ -# Adding your module to the userguide +# Adding your module -Making your module work with the userguide is simple. +Making your module work with the User Guide is simple. -First, copy this config and place in it `/config/userguide.php`, replacing anything in `<>` with the appropriate things: +First, copy this config and place in it `/config/userguide.php`, replacing anything in `<>` with the appropriate values: return array ( // Leave this alone 'modules' => array( - - // This should be the path to this modules userguide pages, without the 'guide/'. Ex: '/guide/modulename/' would be 'modulename' + + /* + * The path to this module's userguide pages, without the 'guide/'. + * + * For example, '/guide/modulename/' would be 'modulename' + */ '' => array( - - // Whether this modules userguide pages should be shown + + // Whether this module's user guide pages should be shown 'enabled' => TRUE, - - // The name that should show up on the userguide index page + + // The name that should show up on the user guide index page 'name' => '', - + // A short description of this module, shown on the index page - 'description' => '', - + 'description' => '', + // Copyright message, shown in the footer for this module - 'copyright' => '© 2010–2011 ', - ) + 'copyright' => '© 2012 ', + ) ), /* - * If you use transparent extension outside the Kohana_ namespace, + * If you use transparent extensions outside the Kohana_ namespace, * add your class prefix here. Both common Kohana naming conventions are - * excluded: + * excluded: * - Modulename extends Modulename_Core * - Foo extends Modulename_Foo - * + * * For example, if you use Modulename_ for your base classes * then you would define: */ @@ -41,7 +45,11 @@ First, copy this config and place in it `/config/userguide.php`, replaci ) ); -Next, create a folder in your module directory called `guide/` and create `index.md` and `menu.md`. All userguide pages use [Markdown](markdown). The index page is what is shown on the index of your module, the menu is what shows up in the side column. The menu should be formatted like this: +Next, create a folder in your module directory called `guide/` and create `index.md` and `menu.md`. The contents of `index.md` is what is shown on the index page of your module. + +## Creating the side menu + +The contents of the `menu.md` file is what shows up in the side column and should be formatted like this: ## [Module Name]() - [Page name](page-path) @@ -52,4 +60,16 @@ Next, create a folder in your module directory called `guide/` and c - Categories do not have to be a link to a page - [Etcetera](etc) -Page paths are relative to `guide/`. So `[Page name](path-path)` would look for `guide//page-name.md` and `[Another](category/another)` would look for `guide//page-name.md`. The guide pages can be named or arranged any way you want within that folder (with the exception of `menu.md` and `index.md`). The breadcrumbs and page titles are pulled from the `menu.md file`, not the file names or paths. You can have items that are not pages (a category that doesn't have a corresponding page). To link to the `index.md` page, you should have an empty link, e.g. `[Module Name]()`. Do not include `.md` in your links. \ No newline at end of file +You can have items that are not linked pages (a category that doesn't have a corresponding page). + +Guide pages can be named or arranged any way you want within that folder (with the exception of `index.md` and `menu.md` which must appear directly below the `guide/` folder). + +## Formatting page titles and links + +Page paths are relative to `guide/`. So `[Page name](page-name)` would look for `guide//page-name.md` and `[Another](category/another)` would look for `guide//category/another.md`. + +The breadcrumbs and page titles are pulled from the `menu.md` file, not the filenames or paths. + +To link to the `index.md` page, you should have an empty link, e.g. `[Module Name]()`. Do not include `.md` in your links. + +All user guide pages use [Markdown](markdown). \ No newline at end of file From f0082206c4a80447b56eb573d215308b140cbe8b Mon Sep 17 00:00:00 2001 From: "T. Zengerink" Date: Wed, 16 Jan 2013 14:52:45 +0100 Subject: [PATCH 03/12] Improved documentation comments - Consistent copyright (2012 -> 2013) - Fixed incorrect license link --- classes/Kohana/Controller/Userguide.php | 60 ++++++++++---------- classes/Kohana/Kodoc.php | 21 ++++--- classes/Kohana/Kodoc/Class.php | 36 ++++++------ classes/Kohana/Kodoc/Markdown.php | 75 +++++++++++++------------ classes/Kohana/Kodoc/Method.php | 12 ++-- classes/Kohana/Kodoc/Method/Param.php | 4 +- classes/Kohana/Kodoc/Missing.php | 2 + classes/Kohana/Kodoc/Property.php | 4 +- config/userguide.php | 8 +-- tests/KodocTest.php | 10 ++-- tests/userguide/ControllerTest.php | 7 ++- 11 files changed, 123 insertions(+), 116 deletions(-) diff --git a/classes/Kohana/Controller/Userguide.php b/classes/Kohana/Controller/Userguide.php index 1c4c10e8..6f8f295b 100644 --- a/classes/Kohana/Controller/Userguide.php +++ b/classes/Kohana/Controller/Userguide.php @@ -3,8 +3,10 @@ * Kohana user guide and api browser. * * @package Kohana/Userguide - * @category Controllers + * @category Controller * @author Kohana Team + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ abstract class Kohana_Controller_Userguide extends Controller_Template { @@ -38,7 +40,7 @@ public function before() // Default show_comments to config value $this->template->show_comments = Kohana::$config->load('userguide.show_comments'); } - + // List all modules that have userguides public function index() { @@ -46,18 +48,18 @@ public function index() $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->show_comments = FALSE; } - + // Display an error if a page isn't found public function error($message) { $this->response->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->show_comments = FALSE; @@ -108,19 +110,19 @@ public function action_docs() { return $this->index(); } - + // If this module's userguide pages are disabled, show the error page if ( ! Kohana::$config->load('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 ) { @@ -135,7 +137,7 @@ public function action_docs() { 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.'/'; @@ -153,7 +155,7 @@ public function action_docs() // Bind the breadcrumb $this->template->bind('breadcrumb', $breadcrumb); - + // Bind the copyright $this->template->copyright = Kohana::$config->load('userguide.modules.'.$module.'.copyright'); @@ -161,9 +163,9 @@ public function action_docs() $breadcrumb = array(); $breadcrumb[$this->guide->uri()] = 'User Guide'; $breadcrumb[$this->guide->uri(array('module' => $module))] = Kohana::$config->load('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') { @@ -193,7 +195,7 @@ public function action_api() { // 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) @@ -208,7 +210,7 @@ public function action_api() // 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 api_packages config setting.'); - + // Everything is fine, display the class. $this->template->title = $class; @@ -245,7 +247,7 @@ public function action_media() { // Check if the browser sent an "if-none-match: " header, and tell if the file hasn't changed $this->check_cache(sha1($this->request->uri()).filemtime($file)); - + // Send the file content as the response $this->response->body(file_get_contents($file)); @@ -323,66 +325,66 @@ public function file($page) 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 Debug::vars($text); - + //$text = preg_replace('/(\s*[\-\*\+]\s*)(.*)/','$1$2',$text); $text = preg_replace('/^(\s*[\-\*\+]\s*)([^\[\]]+)$/m','$1$2',$text); //echo Debug::vars($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->load('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) { @@ -391,7 +393,7 @@ protected function _modules() unset($modules[$key]); } } - + return $modules; } diff --git a/classes/Kohana/Kodoc.php b/classes/Kohana/Kodoc.php index acd9cbcf..24a6b285 100644 --- a/classes/Kohana/Kodoc.php +++ b/classes/Kohana/Kodoc.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2008-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc { @@ -415,12 +415,12 @@ public static function show_class(Kodoc_Class $class) * * Module developers can therefore add their own transparent extension * namespaces and exclude them from the userguide. - * - * @param string $class The name of the class to check for transparency - * @param array $classes An optional list of all defined classes - * @return false If this is not a transparent extension class - * @return string The name of the class that extends this (in the case provided) - * @throws InvalidArgumentException If the $classes array is provided and the $class variable is not lowercase + * + * @param string $class The name of the class to check for transparency + * @param array $classes An optional list of all defined classes + * @return false If this is not a transparent extension class + * @return string The name of the class that extends this (in the case provided) + * @throws InvalidArgumentException If the $classes array is provided and the $class variable is not lowercase */ public static function is_transparent($class, $classes = NULL) { @@ -447,11 +447,11 @@ public static function is_transparent($class, $classes = NULL) // Cater for Foo extends Module_Foo naming $child_class = $segments[1]; } - + // It is only a transparent class if the unprefixed class also exists if ($classes AND ! isset($classes[$child_class])) return FALSE; - + // Return the name of the child class return $child_class; } @@ -462,5 +462,4 @@ public static function is_transparent($class, $classes = NULL) } } - } // End Kodoc diff --git a/classes/Kohana/Kodoc/Class.php b/classes/Kohana/Kodoc/Class.php index 2c2f2f23..9ef9b16a 100644 --- a/classes/Kohana/Kodoc/Class.php +++ b/classes/Kohana/Kodoc/Class.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Class extends Kodoc { @@ -45,7 +45,7 @@ class Kohana_Kodoc_Class extends Kodoc { * the class. Reads the class modifiers, constants and comment. Parses the * comment to find the description and tags. * - * @param string class name + * @param string Class name * @return void */ public function __construct($class) @@ -59,7 +59,7 @@ public function __construct($class) $this->constants = $this->class->getConstants(); - // If ReflectionClass::getParentClass() won't work if the class in + // If ReflectionClass::getParentClass() won't work if the class in // question is an interface if ($this->class->isInterface()) { @@ -154,7 +154,7 @@ public function properties() return $props; } - + protected function _prop_sort($a, $b) { // If one property is public, and the other is not, it goes on top @@ -162,13 +162,13 @@ protected function _prop_sort($a, $b) 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); } @@ -191,14 +191,15 @@ public function methods() 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 + * + * * 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 - * + * * lastly, they will be sorted alphabetically + * */ protected function _method_sort($a, $b) { @@ -207,16 +208,16 @@ protected function _method_sort($a, $b) 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 Debug::vars('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), @@ -276,4 +277,5 @@ public function tags() return $result; } -} + +} // End Kodoc_Class diff --git a/classes/Kohana/Kodoc/Markdown.php b/classes/Kohana/Kodoc/Markdown.php index 856be950..2c488625 100644 --- a/classes/Kohana/Kodoc/Markdown.php +++ b/classes/Kohana/Kodoc/Markdown.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { @@ -19,25 +19,26 @@ class Kohana_Kodoc_Markdown extends MarkdownExtra_Parser { * @var string base url for images */ public static $image_url = ''; - + /** - * Currently defined heading ids. + * Currently defined heading ids. * Used to prevent creating multiple headings with same id. - * @var array + * + * @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; - + /** * Transform some text using [Kodoc_Markdown] * @@ -81,82 +82,82 @@ public function __construct() // 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 + * @param array Matches from regex call + * @return string Generated html */ - function _doHeaders_callback_setext($matches) + 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 = "".$this->runSpanGamut($matches[1]).""; 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 + * @param array Matches from regex call + * @return string Generated html */ - function _doHeaders_callback_atx($matches) + 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(empty($matches[3]) ? $matches[2] : $matches[3])); - + $block = "".$this->runSpanGamut($matches[2]).""; 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 + * @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; } @@ -203,7 +204,7 @@ public function doIncludeViews($text) * * [filesystem](about.filesystem "Optional title") * - * @param string span text + * @param string Span text * @return string */ public function doBaseURL($text) @@ -217,7 +218,7 @@ public function doBaseURL($text) * * ![Install Page](img/install.png "Optional title") * - * @param string span text + * @param string Span text * @return string */ public function doImageURL($text) @@ -231,7 +232,7 @@ public function doImageURL($text) * * [Class_Name], [Class::method] or [Class::$property] * - * @param string span text + * @param string Span text * @return string */ public function doAPI($text) @@ -244,7 +245,7 @@ public function doAPI($text) * * [!!] Remember the milk! * - * @param string span text + * @param string Span text * @return string */ public function doNotes($text) @@ -256,7 +257,7 @@ public function doNotes($text) return $this->hashBlock('

'.$match[1].'

'); } - + protected function _add_to_toc($level, $name, $id) { self::$_toc[] = array( @@ -264,7 +265,7 @@ protected function _add_to_toc($level, $name, $id) 'name' => $name, 'id' => $id); } - + public function doTOC($text) { // Only add the toc do userguide pages, not api since they already have one diff --git a/classes/Kohana/Kodoc/Method.php b/classes/Kohana/Kodoc/Method.php index 2e673d4b..8b26cc27 100644 --- a/classes/Kohana/Kodoc/Method.php +++ b/classes/Kohana/Kodoc/Method.php @@ -5,28 +5,28 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Method extends Kodoc { /** - * @var ReflectionMethod The ReflectionMethod for this class + * @var ReflectionMethod The ReflectionMethod for this class */ public $method; /** - * @var array array of Kodoc_Method_Param + * @var array Array of Kodoc_Method_Param */ public $params; /** - * @var array the things this function can return + * @var array The things this function can return */ public $return = array(); /** - * @var string the source code for this function + * @var string The source code for this function */ public $source; diff --git a/classes/Kohana/Kodoc/Method/Param.php b/classes/Kohana/Kodoc/Method/Param.php index 7b5976fc..a29c0e28 100644 --- a/classes/Kohana/Kodoc/Method/Param.php +++ b/classes/Kohana/Kodoc/Method/Param.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Method_Param extends Kodoc { diff --git a/classes/Kohana/Kodoc/Missing.php b/classes/Kohana/Kodoc/Missing.php index b3ebcdf4..85e841b9 100644 --- a/classes/Kohana/Kodoc/Missing.php +++ b/classes/Kohana/Kodoc/Missing.php @@ -7,6 +7,8 @@ * @package Kohana/Userguide * @category Undocumented * @author Kohana Team + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license * @since 3.0.7 */ abstract class Kohana_Kodoc_Missing { diff --git a/classes/Kohana/Kodoc/Property.php b/classes/Kohana/Kodoc/Property.php index af2cbee4..a4b5bef5 100644 --- a/classes/Kohana/Kodoc/Property.php +++ b/classes/Kohana/Kodoc/Property.php @@ -5,8 +5,8 @@ * @package Kohana/Userguide * @category Base * @author Kohana Team - * @copyright (c) 2009-2012 Kohana Team - * @license http://kohanaphp.com/license + * @copyright (c) 2008-2013 Kohana Team + * @license http://kohanaframework.org/license */ class Kohana_Kodoc_Property extends Kodoc { diff --git a/config/userguide.php b/config/userguide.php index 0258f694..eae38c21 100644 --- a/config/userguide.php +++ b/config/userguide.php @@ -20,16 +20,16 @@ // Whether this modules userguide pages should be shown 'enabled' => TRUE, - + // The name that should show up on the userguide index page 'name' => 'Userguide', // A short description of this module, shown on the index page 'description' => 'Documentation viewer and api generation.', - + // Copyright message, shown in the footer for this module - 'copyright' => '© 2008–2012 Kohana Team', - ) + 'copyright' => '© 2008–2013 Kohana Team', + ) ), // Set transparent class name segments diff --git a/tests/KodocTest.php b/tests/KodocTest.php index 8258f51b..1432547d 100644 --- a/tests/KodocTest.php +++ b/tests/KodocTest.php @@ -6,7 +6,7 @@ * * @package Kohana/Userguide * @author Kohana Team - * @copyright (c) 2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team * @license http://kohanaframework.org/license */ class Kohana_KodocTest extends PHPUnit_Framework_TestCase @@ -88,7 +88,7 @@ public function provider_parse_basic() array( <<<'COMMENT' /** - * @trailingspace + * @trailingspace */ COMMENT , @@ -162,11 +162,11 @@ public function provider_parse_tags() array( <<<'COMMENT' /** - * @copyright (c) 2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team */ COMMENT , - array('', array('copyright' => array('© 2012 Kohana Team'))), + array('', array('copyright' => array('© 2008-2013 Kohana Team'))), ), array( <<<'COMMENT' @@ -328,7 +328,7 @@ public function test_parse_tags($comment, $expected) { $this->assertSame($expected, Kodoc::parse($comment)); } - + /** * Provides test data for test_transparent_classes * @return array diff --git a/tests/userguide/ControllerTest.php b/tests/userguide/ControllerTest.php index 30ef4755..d9f13135 100644 --- a/tests/userguide/ControllerTest.php +++ b/tests/userguide/ControllerTest.php @@ -10,7 +10,7 @@ * @package Kohana/Userguide * @category Tests * @author Kohana Team - * @copyright (c) 2008-2012 Kohana Team + * @copyright (c) 2008-2013 Kohana Team * @license http://kohanaframework.org/license */ class Userguide_ControllerTest extends Unittest_TestCase @@ -28,8 +28,8 @@ public function provider_file_finds_markdown_files() /** * @dataProvider provider_file_finds_markdown_files - * @param string $page Page name passed in the URL - * @param string $expected_file Expected result from Controller_Userguide::file + * @param string $page Page name passed in the URL + * @param string $expected_file Expected result from Controller_Userguide::file */ public function test_file_finds_markdown_files($page, $expected_file) { @@ -42,4 +42,5 @@ public function test_file_finds_markdown_files($page, $expected_file) $this->assertEquals($expected_file, $file); } + } From 52e1b02ccd29d08c787af27767b9112d21bf3a26 Mon Sep 17 00:00:00 2001 From: webking Date: Sat, 3 Aug 2013 21:16:46 +0200 Subject: [PATCH 04/12] Don't show breadcrumbs if there is only one link --- views/userguide/template.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/views/userguide/template.php b/views/userguide/template.php index d94efc4e..d0751aa2 100644 --- a/views/userguide/template.php +++ b/views/userguide/template.php @@ -38,6 +38,7 @@
+ 1): ?>
    $title): ?> @@ -49,6 +50,7 @@
+
From 8d241a2c263e3a90a6bc7f3526f8a0c68cb7dafb Mon Sep 17 00:00:00 2001 From: George Fekete Date: Tue, 27 Aug 2013 23:49:37 +0300 Subject: [PATCH 05/12] Changed sidebar menu style, dropped expand/collapse functionality (refs #4723) --- guide/userguide/menu.md | 15 +++++++++------ media/guide/css/kodoc.css | 16 ++++++++++++++-- media/guide/js/kodoc.js | 35 ----------------------------------- 3 files changed, 23 insertions(+), 43 deletions(-) mode change 100644 => 100755 guide/userguide/menu.md mode change 100644 => 100755 media/guide/css/kodoc.css mode change 100644 => 100755 media/guide/js/kodoc.js diff --git a/guide/userguide/menu.md b/guide/userguide/menu.md old mode 100644 new mode 100755 index e3f53efd..8fed1d2e --- a/guide/userguide/menu.md +++ b/guide/userguide/menu.md @@ -1,7 +1,10 @@ ## [Userguide]() - - [Using the Userguide](using) - - [How userguide works](works) - - [Contributing](contributing) - - [Markdown Syntax](markdown) - - [Configuration](config) - - [Adding your module](adding) \ No newline at end of file + +- Getting Started + - [Using the Userguide](using) + - [How the Userguide works](works) + - [Configuration](config) +- Learning More + - [Contributing](contributing) + - [Markdown Syntax](markdown) + - [Adding your module](adding) \ No newline at end of file diff --git a/media/guide/css/kodoc.css b/media/guide/css/kodoc.css old mode 100644 new mode 100755 index 0807bcc9..5557da22 --- a/media/guide/css/kodoc.css +++ b/media/guide/css/kodoc.css @@ -99,7 +99,7 @@ h6:hover a.permalink { #kodoc-content, #kodoc-footer { float: left; clear: both; width: 100%; } -#kodoc-header { padding: 58px 0 2em; background: #77c244 url(../img/header.png) center top repeat-x; } +#kodoc-header { padding: 20px 0 2em; background: #77c244 url(../img/header.png) center top repeat-x; } #kodoc-logo { display: block; float: left; } #kodoc-menu { float: right; margin-top: 12px; background: #113c32; -moz-border-radius: 5px; -webkit-border-radius: 5px; } #kodoc-menu ul { float: left; margin: 0; padding: 0 0.5em 0 0; } @@ -125,11 +125,23 @@ h6:hover a.permalink { #kodoc-topics { } #kodoc-topics ul, - #kodoc-topics ol { list-style-type:none; margin: 0; padding: 0;} + #kodoc-topics ol { list-style-type:none; margin: 0 0 0 0; padding: 0;} #kodoc-topics ul li, #kodoc-topics ol li { margin:0; padding: 0; margin-left: 1em; } #kodoc-topics ul li a.current, #kodoc-topics ol li a.current { font-weight: bold; } + + #kodoc-topics > ul > li { + margin-bottom: 20px; + } + + #kodoc-topics > ul > li > a, + #kodoc-topics > ul > li > span { + font-weight: bold; + color: #EE8C0E; + } + + #kodoc-topics span, #kodoc-topics a { display: block; padding: 0; margin: 0; } #kodoc-topics span { cursor: pointer; } diff --git a/media/guide/js/kodoc.js b/media/guide/js/kodoc.js old mode 100644 new mode 100755 index 597ebf9b..1dab95d5 --- a/media/guide/js/kodoc.js +++ b/media/guide/js/kodoc.js @@ -32,41 +32,6 @@ $(document).ready(function() }); }); - // Collapsing menus - $('#kodoc-topics li:has(li)').each(function() - { - var $this = $(this); - var toggle = $(''); - var menu = $this.find('>ul,>ol'); - - toggle.click(function() - { - if (menu.is(':visible')) - { - menu.stop(true, true).slideUp('fast'); - toggle.html('+'); - } - else - { - menu.stop(true, true).slideDown('fast'); - toggle.html('–'); - } - }); - - $this.find('>span').click(function() - { - // Menu without a link - toggle.click(); - }); - - if ( ! $this.is(':has(a.current)')) - { - menu.hide(); - } - - toggle.html(menu.is(':visible') ? '–' : '+').prependTo($this); - }); - // Show source links $('#kodoc-main .method-source').each(function() From 23a7981a7d595a0c92420cec76123e01b426b62c Mon Sep 17 00:00:00 2001 From: kostyatretyak Date: Wed, 2 Oct 2013 04:28:06 +0300 Subject: [PATCH 06/12] Added preg_match() for generating link for 'uses constant' --- classes/Kohana/Kodoc.php | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/classes/Kohana/Kodoc.php b/classes/Kohana/Kodoc.php index acd9cbcf..0a8d9d32 100644 --- a/classes/Kohana/Kodoc.php +++ b/classes/Kohana/Kodoc.php @@ -34,6 +34,10 @@ public static function link_class_member($matches) { $member = '#property:'.substr($matches[3], 1); } + elseif (preg_match('/^[A-Z_\x7f-\xff][A-Z0-9_\x7f-\xff]*$/', $matches[3])) + { + $member = '#constant:'.substr($matches[3],0); + } else { $member = '#'.$matches[3]; From e4ef1a36d8ab850f406d2b2f1094288f327a7ce2 Mon Sep 17 00:00:00 2001 From: Paul Schwarz Date: Fri, 24 Jan 2014 23:54:59 +0000 Subject: [PATCH 07/12] Resolves #4814 by removing duplicate line of code. --- classes/kohana/kodoc/markdown.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/classes/kohana/kodoc/markdown.php b/classes/kohana/kodoc/markdown.php index 5e3f0acc..8143b15f 100644 --- a/classes/kohana/kodoc/markdown.php +++ b/classes/kohana/kodoc/markdown.php @@ -166,8 +166,6 @@ public function doIncludeViews($text) { $replace = array(); - $replace = array(); - foreach ($matches as $set) { list($search, $view) = $set; From 8d8d2cb6a06daadefe553be6081a61a8bb3b8fc8 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Wed, 17 Sep 2014 17:38:25 +0100 Subject: [PATCH 08/12] Configure standalone travis build Adds and configures kohana/koharness to build a skeleton Kohana application and then uses that environment to run the unit tests on travis (and locally, if required). Continues kohana/kohana#50 --- .gitignore | 4 ++++ .travis.yml | 24 ++++++++++++++++++++++++ composer.json | 10 +++++++++- koharness.php | 8 ++++++++ 4 files changed, 45 insertions(+), 1 deletion(-) create mode 100644 .travis.yml create mode 100644 koharness.php diff --git a/.gitignore b/.gitignore index fb662418..32b12014 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,7 @@ Icon? .idea *~ *.swp +composer.lock +vendor/* +koharness_bootstrap.php + diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 00000000..8f9e0fca --- /dev/null +++ b/.travis.yml @@ -0,0 +1,24 @@ +language: php + +php: + - 5.3 + - 5.4 + - 5.5 + - 5.6 + - hhvm + +before_script: + - composer install --prefer-dist + - vendor/bin/koharness + +script: + - cd /tmp/koharness && ./vendor/bin/phpunit --bootstrap=modules/unittest/bootstrap.php modules/unittest/tests.php + +notifications: + irc: + channels: + - "irc.freenode.org#kohana" + template: + - "%{repository}/%{branch} (%{commit}) - %{author}: %{message}" + - "Build details: %{build_url}" + email: false diff --git a/composer.json b/composer.json index b27114e8..d1b9cd02 100644 --- a/composer.json +++ b/composer.json @@ -24,10 +24,18 @@ "kohana/core": ">=3.3", "php": ">=5.3.3" }, + "require-dev": { + "kohana/core": "3.3.*@dev", + "kohana/unittest": "3.3.*@dev", + "kohana/koharness": "*@dev" + }, "extra": { "branch-alias": { "dev-3.3/develop": "3.3.x-dev", "dev-3.4/develop": "3.4.x-dev" - } + }, + "installer-paths": { + "vendor/{$vendor}/{$name}": ["type:kohana-module"] + } } } diff --git a/koharness.php b/koharness.php new file mode 100644 index 00000000..0c70d08b --- /dev/null +++ b/koharness.php @@ -0,0 +1,8 @@ + array( + 'userguide' => __DIR__, + 'unittest' => __DIR__ . '/vendor/kohana/unittest' + ), +); From 4d5248d7857c7dd7fead8902cd8fcaef48f21e84 Mon Sep 17 00:00:00 2001 From: Samuel Demirdjian Date: Thu, 18 Sep 2014 11:31:50 +0300 Subject: [PATCH 09/12] Resolves R4814 by removing duplicate line of code --- classes/Kohana/Kodoc/Markdown.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/classes/Kohana/Kodoc/Markdown.php b/classes/Kohana/Kodoc/Markdown.php index 856be950..31dffed5 100644 --- a/classes/Kohana/Kodoc/Markdown.php +++ b/classes/Kohana/Kodoc/Markdown.php @@ -166,8 +166,6 @@ public function doIncludeViews($text) { $replace = array(); - $replace = array(); - foreach ($matches as $set) { list($search, $view) = $set; From 739a07c28012b3bc995d2ef7895404c02eef1f17 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Mon, 22 Sep 2014 17:59:00 +0100 Subject: [PATCH 10/12] Disable IRC notifications for kohana builds --- .travis.yml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.travis.yml b/.travis.yml index 8f9e0fca..1313e377 100644 --- a/.travis.yml +++ b/.travis.yml @@ -15,10 +15,4 @@ script: - cd /tmp/koharness && ./vendor/bin/phpunit --bootstrap=modules/unittest/bootstrap.php modules/unittest/tests.php notifications: - irc: - channels: - - "irc.freenode.org#kohana" - template: - - "%{repository}/%{branch} (%{commit}) - %{author}: %{message}" - - "Build details: %{build_url}" email: false From fa92ea4154974fecbe8414721c30a45eb3736e6d Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Fri, 10 Oct 2014 15:38:26 +0100 Subject: [PATCH 11/12] Add travis build badges [skip ci] --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f79888d2..eae4446a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,10 @@ +# Kohana - userguide module + +| ver | Stable | Develop | +|-------|----------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| +| 3.3.x | [![Build Status - 3.3/master](https://travis-ci.org/kohana/userguide.svg?branch=3.3%2Fmaster)](https://travis-ci.org/kohana/userguide) | [![Build Status - 3.3/develop](https://travis-ci.org/kohana/userguide.svg?branch=3.3%2Fdevelop)](https://travis-ci.org/kohana/userguide) | +| 3.4.x | [![Build Status - 3.4/master](https://travis-ci.org/kohana/userguide.svg?branch=3.4%2Fmaster)](https://travis-ci.org/kohana/userguide) | [![Build Status - 3.4/develop](https://travis-ci.org/kohana/userguide.svg?branch=3.4%2Fdevelop)](https://travis-ci.org/kohana/userguide) | + ## What needs to be done? Most articles are stubs, with a couple links to pages to be used as a reference when writing the page. The idea is to use the information on those links to help write the new ones. Some of the old userguide pages can probably be mostly copied, with a few improvements, others will be better to be completely rewritten. If you ever have questions, please feel free to jump in the kohana irc channel. @@ -66,4 +73,4 @@ If you want to have parameters, only put the brackets around the class and funct You may include a view by putting the name of the view in double curly brackets. **If the view is not found, no exception or error will be shown!** The curly brackets and view will simply be shown an the page as is. - {{some/view}} \ No newline at end of file + {{some/view}} From 18abaa111fd098de8fcf43577bafdbaaca67c477 Mon Sep 17 00:00:00 2001 From: Andrew Coulton Date: Fri, 10 Oct 2014 22:24:30 +0100 Subject: [PATCH 12/12] Update copyright year in userguide footer Identified by @aaronott in #60 but applied manually to target 3.3 and because it's now a year since he changed it and it needs changed again... Closes #60 --- config/userguide.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/userguide.php b/config/userguide.php index eae38c21..4a2d1d9d 100644 --- a/config/userguide.php +++ b/config/userguide.php @@ -28,7 +28,7 @@ 'description' => 'Documentation viewer and api generation.', // Copyright message, shown in the footer for this module - 'copyright' => '© 2008–2013 Kohana Team', + 'copyright' => '© 2008–2014 Kohana Team', ) ),