tonyair/silverstripe-docsviewer
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-docsviewer synced 2024-10-22 09:05:56 +00:00
Code Issues Projects Releases Wiki Activity

Fix some CBF linting issues. Improved a couple of doc blocks.

Browse Source
This commit is contained in:
Robbie Averill 2016-12-05 08:53:53 +13:00
parent a9130a33db
commit 909cfd695f
9 changed files with 178 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
code/DocumentationManifest.php
View File

@ -156,8 +156,8 @@ class DocumentationManifest
foreach ($langs as $k => $lang) { foreach ($langs as $k => $lang) {
if (isset($possible[$lang])) { if (isset($possible[$lang])) {
/** /**
* @var DocumentationEntity $entity * @var DocumentationEntity $entity
*/ */
$entity = Injector::inst()->create( $entity = Injector::inst()->create(
'DocumentationEntity', $key 'DocumentationEntity', $key
); );
@ -769,8 +769,8 @@ class DocumentationManifest
$output = new ArrayList(); $output = new ArrayList();
/** /**
* @var DocumentationEntity $check * @var DocumentationEntity $check
*/ */
foreach ($this->getEntities() as $check) { foreach ($this->getEntities() as $check) {
if ($check->getKey() == $entity->getKey()) { if ($check->getKey() == $entity->getKey()) {
if ($check->getLanguage() == $entity->getLanguage()) { if ($check->getLanguage() == $entity->getLanguage()) {

88
code/DocumentationParser.php
View File

@ -2,7 +2,7 @@
/** /**
* Parser wrapping the Markdown Extra parser. * Parser wrapping the Markdown Extra parser.
* *
* @see http://michelf.com/projects/php-markdown/extra/ * @see http://michelf.com/projects/php-markdown/extra/
* *
* @package docsviewer * @package docsviewer
@ -16,25 +16,25 @@ class DocumentationParser
* @var array * @var array
*/ */
public static $heading_counts = array(); public static $heading_counts = array();
/** /**
* Parse a given path to the documentation for a file. Performs a case * Parse a given path to the documentation for a file. Performs a case
* insensitive lookup on the file system. Automatically appends the file * insensitive lookup on the file system. Automatically appends the file
* extension to one of the markdown extensions as well so /install/ in a * extension to one of the markdown extensions as well so /install/ in a
* web browser will match /install.md or /INSTALL.md. * web browser will match /install.md or /INSTALL.md.
* *
* Filepath: /var/www/myproject/src/cms/en/folder/subfolder/page.md * Filepath: /var/www/myproject/src/cms/en/folder/subfolder/page.md
* URL: http://myhost/mywebroot/dev/docs/2.4/cms/en/folder/subfolder/page * URL: http://myhost/mywebroot/dev/docs/2.4/cms/en/folder/subfolder/page
* Webroot: http://myhost/mywebroot/ * Webroot: http://myhost/mywebroot/
* Baselink: dev/docs/2.4/cms/en/ * Baselink: dev/docs/2.4/cms/en/
* Pathparts: folder/subfolder/page * Pathparts: folder/subfolder/page
*
* @param DocumentationPage $page
* @param String $baselink Link relative to webroot, up until the "root" of the module. Necessary to rewrite relative links
* of the module. Necessary to rewrite relative
* links
* *
* @return String * @param DocumentationPage $page
* @param string $baselink Link relative to webroot, up until the "root" of the module.
* Necessary to rewrite relative links of the module. Necessary
* to rewrite relative links
*
* @return string
*/ */
public static function parse(DocumentationPage $page, $baselink = null) public static function parse(DocumentationPage $page, $baselink = null)
{ {
@ -43,7 +43,7 @@ class DocumentationParser
} }
$md = $page->getMarkdown(true); $md = $page->getMarkdown(true);
// Pre-processing // Pre-processing
$md = self::rewrite_image_links($md, $page); $md = self::rewrite_image_links($md, $page);
$md = self::rewrite_relative_links($md, $page, $baselink); $md = self::rewrite_relative_links($md, $page, $baselink);
@ -60,7 +60,7 @@ class DocumentationParser
return $text; return $text;
} }
public static function rewrite_code_blocks($md) public static function rewrite_code_blocks($md)
{ {
$started = false; $started = false;
@ -148,8 +148,8 @@ class DocumentationParser
var_dump('Inner line of code block'); var_dump('Inner line of code block');
} }
// still inside a colon based block, if the line is only whitespace // still inside a colon based block, if the line is only whitespace
// then continue with with it. We can continue with it for now as // then continue with with it. We can continue with it for now as
// it'll be tidied up later in the $end section. // it'll be tidied up later in the $end section.
$inner = true; $inner = true;
$output[$i] = $line; $output[$i] = $line;
@ -210,7 +210,7 @@ class DocumentationParser
return $output; return $output;
} }
public static function rewrite_image_links($md, $page) public static function rewrite_image_links($md, $page)
{ {
// Links with titles // Links with titles
@ -229,14 +229,14 @@ class DocumentationParser
foreach ($images[0] as $i => $match) { foreach ($images[0] as $i => $match) {
$title = $images[1][$i]; $title = $images[1][$i];
$url = $images[2][$i]; $url = $images[2][$i];
// Don't process absolute links (based on protocol detection) // Don't process absolute links (based on protocol detection)
$urlParts = parse_url($url); $urlParts = parse_url($url);
if ($urlParts && isset($urlParts['scheme'])) { if ($urlParts && isset($urlParts['scheme'])) {
continue; continue;
} }
// Rewrite URL (relative or absolute) // Rewrite URL (relative or absolute)
$baselink = DocumentationHelper::relativePath( $baselink = DocumentationHelper::relativePath(
DocumentationHelper::normalizePath( DocumentationHelper::normalizePath(
@ -262,13 +262,13 @@ class DocumentationParser
while (strpos($relativeUrl, '/..') !== false) { while (strpos($relativeUrl, '/..') !== false) {
$relativeUrl = preg_replace('/\w+\/\.\.\//', '', $relativeUrl); $relativeUrl = preg_replace('/\w+\/\.\.\//', '', $relativeUrl);
} }
// Make it absolute again // Make it absolute again
$absoluteUrl = Controller::join_links( $absoluteUrl = Controller::join_links(
Director::absoluteBaseURL(), Director::absoluteBaseURL(),
$relativeUrl $relativeUrl
); );
// Replace any double slashes (apart from protocol) // Replace any double slashes (apart from protocol)
// $absoluteUrl = preg_replace('/([^:])\/{2,}/', '$1/', $absoluteUrl); // $absoluteUrl = preg_replace('/([^:])\/{2,}/', '$1/', $absoluteUrl);
@ -280,20 +280,20 @@ class DocumentationParser
); );
} }
} }
return $md; return $md;
} }
/** /**
* Rewrite links with special "api:" prefix to html as in the following example: * Rewrite links with special "api:" prefix to html as in the following example:
* *
* (1) [api:DataObject] gets re-written to * (1) [api:DataObject] gets re-written to
* <a href="https://api.silverstripe.org/search/lookup/?q=DataObject&version=2.4&module=framework">DataObject</a> * <a href="https://api.silverstripe.org/search/lookup/?q=DataObject&version=2.4&module=framework">DataObject</a>
* (2) [api:DataObject::$defaults] gets re-written to * (2) [api:DataObject::$defaults] gets re-written to
* <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::$defaults&version=2.4&module=framework">DataObject::$defaults</a> * <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::$defaults&version=2.4&module=framework">DataObject::$defaults</a>
* (3) [api:DataObject::populateDefaults()] gets re-written to * (3) [api:DataObject::populateDefaults()] gets re-written to
* <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::populateDefaults()&version=2.4&module=framework">DataObject::$defaults</a> * <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::populateDefaults()&version=2.4&module=framework">DataObject::$defaults</a>
* (4) [Title](api:DataObject) gets re-written to * (4) [Title](api:DataObject) gets re-written to
* <a href="https://api.silverstripe.org/search/lookup/?q=DataObject&version=2.4&module=framework">Title</a> * <a href="https://api.silverstripe.org/search/lookup/?q=DataObject&version=2.4&module=framework">Title</a>
* (5) [Title](api:DataObject::$defaults) gets re-written to * (5) [Title](api:DataObject::$defaults) gets re-written to
* <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::$defaults&version=2.4&module=framework">Title</a> * <a href="https://api.silverstripe.org/search/lookup/?q=DataObject::$defaults&version=2.4&module=framework">Title</a>
@ -302,9 +302,9 @@ class DocumentationParser
* *
* The above api links can be enclosed in backticks. * The above api links can be enclosed in backticks.
* *
* The markdown parser gets confused by the extra pair of parentheses in links of the form [DataObject](api:DataObject::populateDefaults()) so * The markdown parser gets confused by the extra pair of parentheses in links of the form [DataObject](api:DataObject::populateDefaults()) so
* all links are re-written as html markup instead of markdown [Title](url). This also prevents other markdown parsing problems. * all links are re-written as html markup instead of markdown [Title](url). This also prevents other markdown parsing problems.
* *
* @param String $markdown * @param String $markdown
* @param DocumentationPage $doc_page * @param DocumentationPage $doc_page
* @return String * @return String
@ -334,7 +334,7 @@ class DocumentationParser
$title = $links[1][$i]; $title = $links[1][$i];
$link = $links[1][$i]; $link = $links[1][$i];
// change backticked links to avoid being parsed in the same way as non-backticked links // change backticked links to avoid being parsed in the same way as non-backticked links
$markdown = str_replace('`'.$match.'`', 'XYZ'.$link.'XYZ', $markdown); $markdown = str_replace('`'.$match.'`', 'XYZ'.$link.'XYZ', $markdown);
} else { } else {
$title = $links[1][$i]; $title = $links[1][$i];
$link = $links[2][$i]; $link = $links[2][$i];
@ -347,7 +347,7 @@ class DocumentationParser
} }
} }
// recover backticked links with no titles // recover backticked links with no titles
preg_match_all('#XYZ(.*)?XYZ#', $markdown, $links); preg_match_all('#XYZ(.*)?XYZ#', $markdown, $links);
if($links) { if($links) {
foreach($links[0] as $i => $match) { foreach($links[0] as $i => $match) {
@ -369,7 +369,7 @@ class DocumentationParser
return $markdown; return $markdown;
} }
/** /**
* *
*/ */
@ -377,10 +377,10 @@ class DocumentationParser
{ {
$re = '/^\#+(.*)/m'; $re = '/^\#+(.*)/m';
$md = preg_replace_callback($re, array('DocumentationParser', '_rewrite_heading_anchors_callback'), $md); $md = preg_replace_callback($re, array('DocumentationParser', '_rewrite_heading_anchors_callback'), $md);
return $md; return $md;
} }
/** /**
* *
*/ */
@ -402,10 +402,10 @@ class DocumentationParser
return sprintf("%s {#%s}", preg_replace('/\\r\\n|\\r|\\n/', '', $heading), self::generate_html_id($headingText)); return sprintf("%s {#%s}", preg_replace('/\\r\\n|\\r|\\n/', '', $heading), self::generate_html_id($headingText));
} }
/** /**
* Generate an html element id from a string * Generate an html element id from a string
* *
* @return String * @return String
*/ */
public static function generate_html_id($title) public static function generate_html_id($title)
@ -417,13 +417,13 @@ class DocumentationParser
$t = preg_replace('/-+/', '-', $t); $t = preg_replace('/-+/', '-', $t);
$t = trim($t, '-'); $t = trim($t, '-');
$t = strtolower($t); $t = strtolower($t);
return $t; return $t;
} }
/** /**
* Resolves all relative links within markdown. * Resolves all relative links within markdown.
* *
* @param String $md Markdown content * @param String $md Markdown content
* @param DocumentationPage $page * @param DocumentationPage $page
* *
@ -461,20 +461,20 @@ class DocumentationParser
if ($relativeLink == ".") { if ($relativeLink == ".") {
$relativeLink = ''; $relativeLink = '';
} }
// file base link // file base link
$fileBaseLink = DocumentationHelper::relativePath(DocumentationHelper::normalizePath(dirname($page->getPath()))); $fileBaseLink = DocumentationHelper::relativePath(DocumentationHelper::normalizePath(dirname($page->getPath())));
if ($matches) { if ($matches) {
foreach ($matches[0] as $i => $match) { foreach ($matches[0] as $i => $match) {
$title = $matches[2][$i]; $title = $matches[2][$i];
$url = $matches[3][$i]; $url = $matches[3][$i];
// Don't process API links // Don't process API links
if (preg_match('/^api:/', $url)) { if (preg_match('/^api:/', $url)) {
continue; continue;
} }
// Don't process absolute links (based on protocol detection) // Don't process absolute links (based on protocol detection)
$urlParts = parse_url($url); $urlParts = parse_url($url);
if ($urlParts && isset($urlParts['scheme'])) { if ($urlParts && isset($urlParts['scheme'])) {
@ -501,12 +501,12 @@ class DocumentationParser
$relativeUrl = Controller::join_links($baselink, $relativeLink, $url, '/'); $relativeUrl = Controller::join_links($baselink, $relativeLink, $url, '/');
} }
} }
// Resolve relative paths // Resolve relative paths
while (strpos($relativeUrl, '..') !== false) { while (strpos($relativeUrl, '..') !== false) {
$relativeUrl = preg_replace('/[-\w]+\/\.\.\//', '', $relativeUrl); $relativeUrl = preg_replace('/[-\w]+\/\.\.\//', '', $relativeUrl);
} }
// Replace any double slashes (apart from protocol) // Replace any double slashes (apart from protocol)
$relativeUrl = preg_replace('/([^:])\/{2,}/', '$1/', $relativeUrl); $relativeUrl = preg_replace('/([^:])\/{2,}/', '$1/', $relativeUrl);
@ -518,10 +518,10 @@ class DocumentationParser
); );
} }
} }
return $md; return $md;
} }
/** /**
* Strips out the metadata for a page * Strips out the metadata for a page
* *

41
code/controllers/DocumentationViewer.php
View File

@ -117,14 +117,14 @@ class DocumentationViewer extends Controller implements PermissionProvider
); );
} }
} }
/** /**
* Permission provider to allow more control over who can view docs * Permission provider to allow more control over who can view docs
* *
* @return array * @return array
*/ */
public function providePermissions() public function providePermissions()
{ {
return array( return array(
'CMS_VIEW_DEVDOCS' => array( 'CMS_VIEW_DEVDOCS' => array(
@ -400,11 +400,11 @@ class DocumentationViewer extends Controller implements PermissionProvider
$output->push( $output->push(
new ArrayData( new ArrayData(
array( array(
'Title' => $entity->getTitle(), 'Title' => $entity->getTitle(),
'Link' => $link, 'Link' => $link,
'LinkingMode' => $mode, 'LinkingMode' => $mode,
'DefaultEntity' => $entity->getIsDefaultEntity(), 'DefaultEntity' => $entity->getIsDefaultEntity(),
'Children' => $children 'Children' => $children
) )
) )
); );
@ -467,7 +467,7 @@ class DocumentationViewer extends Controller implements PermissionProvider
return $this->customise( return $this->customise(
new ArrayData( new ArrayData(
array( array(
'Children' => $children 'Children' => $children
) )
) )
)->renderWith('Includes/DocumentationPages'); )->renderWith('Includes/DocumentationPages');
@ -587,9 +587,9 @@ class DocumentationViewer extends Controller implements PermissionProvider
$output->push( $output->push(
new ArrayData( new ArrayData(
array( array(
'Link' => Controller::join_links($baseLink, $url), 'Link' => Controller::join_links($baseLink, $url),
'Title' => $page['title'], 'Title' => $page['title'],
'FirstLetter' => $first 'FirstLetter' => $first
) )
) )
); );
@ -622,14 +622,14 @@ class DocumentationViewer extends Controller implements PermissionProvider
* - %version% * - %version%
* - %entity% * - %entity%
* - %path% * - %path%
* - %lang% * - %lang%
* *
* For example to provide an edit link to the framework module in github: * For example to provide an edit link to the framework module in github:
* *
* <code> * <code>
* DocumentationViewer::set_edit_link( * DocumentationViewer::set_edit_link(
* 'framework', * 'framework',
* 'https://github.com/silverstripe/%entity%/edit/%version%/docs/%lang%/%path%', * 'https://github.com/silverstripe/%entity%/edit/%version%/docs/%lang%/%path%',
* $opts * $opts
* )); * ));
* </code> * </code>
@ -658,8 +658,6 @@ class DocumentationViewer extends Controller implements PermissionProvider
if ($page) { if ($page) {
$entity = $page->getEntity(); $entity = $page->getEntity();
if ($entity && isset(self::$edit_links[strtolower($entity->title)])) { if ($entity && isset(self::$edit_links[strtolower($entity->title)])) {
// build the edit link, using the version defined // build the edit link, using the version defined
@ -671,7 +669,7 @@ class DocumentationViewer extends Controller implements PermissionProvider
} }
if ($version == "trunk" && (isset($url['options']['rewritetrunktomaster']))) { if ($version == 'trunk' && (isset($url['options']['rewritetrunktomaster']))) {
if ($url['options']['rewritetrunktomaster']) { if ($url['options']['rewritetrunktomaster']) {
$version = "master"; $version = "master";
} }
@ -699,7 +697,7 @@ class DocumentationViewer extends Controller implements PermissionProvider
* Returns the next page. Either retrieves the sibling of the current page * Returns the next page. Either retrieves the sibling of the current page
* or return the next sibling of the parent page. * or return the next sibling of the parent page.
* *
* @return DocumentationPage * @return DocumentationPage|null
*/ */
public function getNextPage() public function getNextPage()
{ {
@ -714,7 +712,7 @@ class DocumentationViewer extends Controller implements PermissionProvider
* Returns the previous page. Either returns the previous sibling or the * Returns the previous page. Either returns the previous sibling or the
* parent of this page * parent of this page
* *
* @return DocumentationPage * @return DocumentationPage|null
*/ */
public function getPreviousPage() public function getPreviousPage()
{ {
@ -726,7 +724,7 @@ class DocumentationViewer extends Controller implements PermissionProvider
} }
/** /**
* @return string * @return string|void
*/ */
public function getGoogleAnalyticsCode() public function getGoogleAnalyticsCode()
{ {
@ -745,6 +743,9 @@ class DocumentationViewer extends Controller implements PermissionProvider
return $this->config()->get('documentation_title'); return $this->config()->get('documentation_title');
} }
/**
* @return string
*/
public function getDocumentationBaseHref() public function getDocumentationBaseHref()
{ {
return Config::inst()->get('DocumentationViewer', 'link_base'); return Config::inst()->get('DocumentationViewer', 'link_base');

12
code/extensions/DocumentationStaticPublisherExtension.php
View File

@ -10,14 +10,14 @@
* <code> * <code>
* StaticExporter: * StaticExporter:
* extensions: * extensions:
* - DocumentationStaticPublisherExtension * - DocumentationStaticPublisherExtension
* </code> * </code>
* *
* If you don't plan on using static publisher for anything else and you have * If you don't plan on using static publisher for anything else and you have
* the cms module installed, make sure you disable that from being published. * the cms module installed, make sure you disable that from being published.
* *
* Again, in your applications config.yml file * Again, in your applications config.yml file
* *
* <code> * <code>
* StaticExporter: * StaticExporter:
* disable_sitetree_export: true * disable_sitetree_export: true
@ -30,7 +30,7 @@ class DocumentationStaticPublisherExtension extends Extension
public function alterExportUrls(&$urls) public function alterExportUrls(&$urls)
{ {
$manifest = new DocumentationManifest(true); $manifest = new DocumentationManifest(true);
foreach ($manifest->getPages() as $url => $page) { foreach ($manifest->getPages() as $url => $page) {
$urls[$url] = $url; $urls[$url] = $url;
} }

27
code/extensions/DocumentationViewerVersionWarning.php
View File

@ -1,14 +1,15 @@
<?php <?php
/** /**
* Check to see if the currently accessed version is out of date or perhaps a * @package docsviewer
* future version rather than the stable edition.
*
* @return false|ArrayData
*/ */
class DocumentationViewerVersionWarning extends Extension class DocumentationViewerVersionWarning extends Extension
{ {
/**
* Check to see if the currently accessed version is out of date or perhaps a
* future version rather than the stable edition.
*
* @return false|ArrayData
*/
public function VersionWarning() public function VersionWarning()
{ {
$page = $this->owner->getPage(); $page = $this->owner->getPage();
@ -16,7 +17,7 @@ class DocumentationViewerVersionWarning extends Extension
if (!$page) { if (!$page) {
return false; return false;
} }
$entity = $page->getEntity(); $entity = $page->getEntity();
if (!$entity) { if (!$entity) {
@ -32,12 +33,12 @@ class DocumentationViewerVersionWarning extends Extension
$stable = $this->owner->getManifest()->getStableVersion($entity); $stable = $this->owner->getManifest()->getStableVersion($entity);
$compare = $entity->compare($stable); $compare = $entity->compare($stable);
if ($entity->getVersion() == "master" || $compare > 0) { if ($entity->getVersion() == 'master' || $compare > 0) {
return $this->owner->customise( return $this->owner->customise(
new ArrayData( new ArrayData(
array( array(
'FutureRelease' => true, 'FutureRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable->getVersion()) 'StableVersion' => DBField::create_field('HTMLText', $stable->getVersion())
) )
) )
); );
@ -45,13 +46,13 @@ class DocumentationViewerVersionWarning extends Extension
return $this->owner->customise( return $this->owner->customise(
new ArrayData( new ArrayData(
array( array(
'OutdatedRelease' => true, 'OutdatedRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable->getVersion()) 'StableVersion' => DBField::create_field('HTMLText', $stable->getVersion())
) )
) )
); );
} }
return false; return false;
} }
} }

23
code/models/DocumentationEntity.php
View File

@ -255,7 +255,7 @@ class DocumentationEntity extends ViewableData
* *
* @return string * @return string
*/ */
public function getVersionTitle() public function getVersionTitle()
{ {
return $this->versionTitle; return $this->versionTitle;
} }
@ -266,7 +266,7 @@ class DocumentationEntity extends ViewableData
* @param string $title * @param string $title
* @return $this * @return $this
*/ */
public function setVersionTitle($title) public function setVersionTitle($title)
{ {
$this->versionTitle = $title; $this->versionTitle = $title;
return $this; return $this;
@ -278,7 +278,7 @@ class DocumentationEntity extends ViewableData
* @param bool $archived * @param bool $archived
* @return $this * @return $this
*/ */
public function setIsArchived($archived) public function setIsArchived($archived)
{ {
$this->archived = $archived; $this->archived = $archived;
return $this; return $this;
@ -287,7 +287,7 @@ class DocumentationEntity extends ViewableData
/** /**
* @return bool * @return bool
*/ */
public function getIsArchived() public function getIsArchived()
{ {
return $this->archived; return $this->archived;
} }
@ -320,8 +320,7 @@ class DocumentationEntity extends ViewableData
} }
/** /**
* @param string $path * @param string $path
*
* @return $this * @return $this
*/ */
public function setPath($path) public function setPath($path)
@ -350,8 +349,6 @@ class DocumentationEntity extends ViewableData
return $this->stable; return $this->stable;
} }
/** /**
* Returns an integer value based on if a given version is the latest * Returns an integer value based on if a given version is the latest
* version. Will return -1 for if the version is older, 0 if versions are * version. Will return -1 for if the version is older, 0 if versions are
@ -367,7 +364,7 @@ class DocumentationEntity extends ViewableData
// Normalise versions prior to comparison // Normalise versions prior to comparison
$dots = substr_count($v1, '.') - substr_count($v2, '.'); $dots = substr_count($v1, '.') - substr_count($v2, '.');
while($dots > 0) { while ($dots > 0) {
$dots--; $dots--;
$v2 .= '.99999'; $v2 .= '.99999';
} }
@ -384,10 +381,10 @@ class DocumentationEntity extends ViewableData
public function toMap() public function toMap()
{ {
return array( return array(
'Key' => $this->key, 'Key' => $this->key,
'Path' => $this->getPath(), 'Path' => $this->getPath(),
'Version' => $this->getVersion(), 'Version' => $this->getVersion(),
'Branch' => $this->getBranch(), 'Branch' => $this->getBranch(),
'IsStable' => $this->getIsStable(), 'IsStable' => $this->getIsStable(),
'Language' => $this->getLanguage() 'Language' => $this->getLanguage()
); );

74
code/models/DocumentationPage.php
View File

@ -1,12 +1,12 @@
<?php <?php
/** /**
* A specific documentation page within a {@link DocumentationEntity}. * A specific documentation page within a {@link DocumentationEntity}.
*
* Maps to a file on the file system. Note that the URL to access this page may
* not always be the file name. If the file contains meta data with a nicer URL
* sthen it will use that.
* *
* Maps to a file on the file system. Note that the URL to access this page may
* not always be the file name. If the file contains meta data with a nicer URL
* sthen it will use that.
*
* @package docsviewer * @package docsviewer
* @subpackage model * @subpackage model
*/ */
@ -55,7 +55,7 @@ class DocumentationPage extends ViewableData
{ {
return DocumentationHelper::get_extension($this->filename); return DocumentationHelper::get_extension($this->filename);
} }
/** /**
* @param string - has to be plain text for open search compatibility. * @param string - has to be plain text for open search compatibility.
* *
@ -64,17 +64,19 @@ class DocumentationPage extends ViewableData
public function getBreadcrumbTitle($divider = ' - ') public function getBreadcrumbTitle($divider = ' - ')
{ {
$pathParts = explode('/', trim($this->getRelativePath(), '/')); $pathParts = explode('/', trim($this->getRelativePath(), '/'));
// from the page from this // from the page from this
array_pop($pathParts); array_pop($pathParts);
// add the module to the breadcrumb trail. // add the module to the breadcrumb trail.
$pathParts[] = $this->entity->getTitle(); $pathParts[] = $this->entity->getTitle();
$titleParts = array_map( $titleParts = array_map(
array( array(
'DocumentationHelper', 'clean_page_name' 'DocumentationHelper',
), $pathParts 'clean_page_name'
),
$pathParts
); );
$titleParts = array_filter( $titleParts = array_filter(
@ -91,7 +93,7 @@ class DocumentationPage extends ViewableData
return implode($divider, $titleParts); return implode($divider, $titleParts);
} }
/** /**
* @return DocumentationEntity * @return DocumentationEntity
*/ */
@ -111,7 +113,7 @@ class DocumentationPage extends ViewableData
$page = DocumentationHelper::clean_page_name($this->filename); $page = DocumentationHelper::clean_page_name($this->filename);
if ($page == "Index") { if ($page == 'Index') {
return $this->getTitleFromFolder(); return $this->getTitleFromFolder();
} }
@ -124,7 +126,7 @@ class DocumentationPage extends ViewableData
$entity = $this->getEntity()->getPath(); $entity = $this->getEntity()->getPath();
$folder = str_replace('index.md', '', $folder); $folder = str_replace('index.md', '', $folder);
// if it's the root of the entity then we want to use the entity name // if it's the root of the entity then we want to use the entity name
// otherwise we'll get 'En' for the entity folder // otherwise we'll get 'En' for the entity folder
if ($folder == $entity) { if ($folder == $entity) {
@ -136,7 +138,7 @@ class DocumentationPage extends ViewableData
return DocumentationHelper::clean_page_name($folderName); return DocumentationHelper::clean_page_name($folderName);
} }
/** /**
* @return string * @return string
*/ */
@ -146,25 +148,25 @@ class DocumentationPage extends ViewableData
} }
/** /**
* Return the raw markdown for a given documentation page. * Return the raw markdown for a given documentation page.
* *
* @param boolean $removeMetaData * @param boolean $removeMetaData
* *
* @return string * @return string|false
*/ */
public function getMarkdown($removeMetaData = false) public function getMarkdown($removeMetaData = false)
{ {
try { try {
if (is_file($this->getPath()) && $md = file_get_contents($this->getPath())) { if (is_file($this->getPath()) && $md = file_get_contents($this->getPath())) {
$this->populateMetaDataFromText($md, $removeMetaData); $this->populateMetaDataFromText($md, $removeMetaData);
return $md; return $md;
} }
$this->read = true; $this->read = true;
} catch (InvalidArgumentException $e) { } catch (InvalidArgumentException $e) {
} }
return false; return false;
} }
@ -175,19 +177,22 @@ class DocumentationPage extends ViewableData
$this->$key = $value; $this->$key = $value;
} }
/**
* @return string
*/
public function getIntroduction() public function getIntroduction()
{ {
if (!$this->read) { if (!$this->read) {
$this->getMarkdown(); $this->getMarkdown();
} }
return $this->introduction; return $this->introduction;
} }
/** /**
* Parse a file and return the parsed HTML version. * Parse a file and return the parsed HTML version.
* *
* @param string $baselink * @param string $baselink
* *
* @return string * @return string
*/ */
@ -200,10 +205,10 @@ class DocumentationPage extends ViewableData
return $html; return $html;
} }
/** /**
* This should return the link from the entity root to the page. The link * This should return the link from the entity root to the page. The link
* value has the cleaned version of the folder names. See * value has the cleaned version of the folder names. See
* {@link getRelativePath()} for the actual file path. * {@link getRelativePath()} for the actual file path.
* *
* @return string * @return string
@ -213,10 +218,12 @@ class DocumentationPage extends ViewableData
$path = $this->getRelativePath(); $path = $this->getRelativePath();
$url = explode('/', $path); $url = explode('/', $path);
$url = implode( $url = implode(
'/', array_map( '/',
array_map(
function ($a) { function ($a) {
return DocumentationHelper::clean_page_url($a); return DocumentationHelper::clean_page_url($a);
}, $url },
$url
) )
); );
@ -245,7 +252,7 @@ class DocumentationPage extends ViewableData
} }
/** /**
* Returns the URL that will be required for the user to hit to view the * Returns the URL that will be required for the user to hit to view the
* given document base name. * given document base name.
* *
* @param boolean $short If true, will attempt to return a short version of the url * @param boolean $short If true, will attempt to return a short version of the url
@ -261,11 +268,11 @@ class DocumentationPage extends ViewableData
), '/' ), '/'
); );
} }
/** /**
* Return metadata from the first html block in the page, then remove the * Return metadata from the first html block in the page, then remove the
* block on request * block on request
* *
* @param DocumentationPage $md * @param DocumentationPage $md
* @param bool $remove * @param bool $remove
*/ */
@ -278,11 +285,11 @@ class DocumentationPage extends ViewableData
if ($matches && $block[1]) { if ($matches && $block[1]) {
$metaDataFound = false; $metaDataFound = false;
// find the key/value pairs // find the key/value pairs
$intPattern = '/(?<key>[A-Za-z][A-Za-z0-9_-]+)[\t]*:[\t]*(?<value>[^:\n\r\/]+)/x'; $intPattern = '/(?<key>[A-Za-z][A-Za-z0-9_-]+)[\t]*:[\t]*(?<value>[^:\n\r\/]+)/x';
$matches = preg_match_all($intPattern, $block[1], $meta); $matches = preg_match_all($intPattern, $block[1], $meta);
foreach ($meta['key'] as $index => $key) { foreach ($meta['key'] as $index => $key) {
if (isset($meta['value'][$index])) { if (isset($meta['value'][$index])) {
// check if a property exists for this key // check if a property exists for this key
@ -293,7 +300,7 @@ class DocumentationPage extends ViewableData
} }
} }
// optionally remove the metadata block (only on the page that // optionally remove the metadata block (only on the page that
// is displayed) // is displayed)
if ($metaDataFound && $removeMetaData) { if ($metaDataFound && $removeMetaData) {
$md = preg_replace($extPattern, '', $md); $md = preg_replace($extPattern, '', $md);
@ -307,6 +314,9 @@ class DocumentationPage extends ViewableData
return $this->entity->getVersion(); return $this->entity->getVersion();
} }
/**
* @return string
*/
public function __toString() public function __toString()
{ {
return sprintf(get_class($this) .': %s)', $this->getPath()); return sprintf(get_class($this) .': %s)', $this->getPath());

33
tests/DocumentationHelperTests.php
View File

@ -9,7 +9,8 @@ class DocumentationHelperTests extends SapphireTest
public function testCleanName() public function testCleanName()
{ {
$this->assertEquals( $this->assertEquals(
"File path", DocumentationHelper::clean_page_name( 'File path',
DocumentationHelper::clean_page_name(
'00_file-path.md' '00_file-path.md'
) )
); );
@ -18,13 +19,15 @@ class DocumentationHelperTests extends SapphireTest
public function testCleanUrl() public function testCleanUrl()
{ {
$this->assertEquals( $this->assertEquals(
"some_path", DocumentationHelper::clean_page_url( 'some_path',
DocumentationHelper::clean_page_url(
'Some Path' 'Some Path'
) )
); );
$this->assertEquals( $this->assertEquals(
"somefilepath", DocumentationHelper::clean_page_url( 'somefilepath',
DocumentationHelper::clean_page_url(
'00_SomeFilePath.md' '00_SomeFilePath.md'
) )
); );
@ -33,19 +36,22 @@ class DocumentationHelperTests extends SapphireTest
public function testTrimSortNumber() public function testTrimSortNumber()
{ {
$this->assertEquals( $this->assertEquals(
'file', DocumentationHelper::trim_sort_number( 'file',
DocumentationHelper::trim_sort_number(
'0_file' '0_file'
) )
); );
$this->assertEquals( $this->assertEquals(
'2.1', DocumentationHelper::trim_sort_number( '2.1',
DocumentationHelper::trim_sort_number(
'2.1' '2.1'
) )
); );
$this->assertEquals( $this->assertEquals(
'dev/tasks/2.1', DocumentationHelper::trim_sort_number( 'dev/tasks/2.1',
DocumentationHelper::trim_sort_number(
'dev/tasks/2.1' 'dev/tasks/2.1'
) )
); );
@ -54,13 +60,15 @@ class DocumentationHelperTests extends SapphireTest
public function testTrimExtension() public function testTrimExtension()
{ {
$this->assertEquals( $this->assertEquals(
'file', DocumentationHelper::trim_extension_off( 'file',
DocumentationHelper::trim_extension_off(
'file.md' 'file.md'
) )
); );
$this->assertEquals( $this->assertEquals(
'dev/path/file', DocumentationHelper::trim_extension_off( 'dev/path/file',
DocumentationHelper::trim_extension_off(
'dev/path/file.md' 'dev/path/file.md'
) )
); );
@ -69,19 +77,22 @@ class DocumentationHelperTests extends SapphireTest
public function testGetExtension() public function testGetExtension()
{ {
$this->assertEquals( $this->assertEquals(
'md', DocumentationHelper::get_extension( 'md',
DocumentationHelper::get_extension(
'file.md' 'file.md'
) )
); );
$this->assertEquals( $this->assertEquals(
'md', DocumentationHelper::get_extension( 'md',
DocumentationHelper::get_extension(
'dev/tasks/file.md' 'dev/tasks/file.md'
) )
); );
$this->assertEquals( $this->assertEquals(
'txt', DocumentationHelper::get_extension( 'txt',
DocumentationHelper::get_extension(
'dev/tasks/file.txt' 'dev/tasks/file.txt'
) )
); );

25
tests/DocumentationManifestTests.php
View File

@ -14,7 +14,7 @@ class DocumentationManifestTests extends SapphireTest
Config::nest(); Config::nest();
// explicitly use dev/docs. Custom paths should be tested separately // explicitly use dev/docs. Custom paths should be tested separately
Config::inst()->update( Config::inst()->update(
'DocumentationViewer', 'link_base', 'dev/docs' 'DocumentationViewer', 'link_base', 'dev/docs'
); );
@ -57,11 +57,11 @@ class DocumentationManifestTests extends SapphireTest
$this->manifest = new DocumentationManifest(true); $this->manifest = new DocumentationManifest(true);
} }
public function tearDown() public function tearDown()
{ {
parent::tearDown(); parent::tearDown();
Config::unnest(); Config::unnest();
} }
@ -108,7 +108,8 @@ class DocumentationManifestTests extends SapphireTest
// get next page at the end of one subfolder goes back up to the top // get next page at the end of one subfolder goes back up to the top
// most directory // most directory
$this->assertStringEndsWith( $this->assertStringEndsWith(
'2.3/test/', $this->manifest->getNextPage( '2.3/test/',
$this->manifest->getNextPage(
DOCSVIEWER_PATH . '/tests/docs/en/subfolder/subsubfolder/subsubpage.md', DOCSVIEWER_PATH . '/tests/docs/en/subfolder/subsubfolder/subsubpage.md',
DOCSVIEWER_PATH . '/tests/docs/en/' DOCSVIEWER_PATH . '/tests/docs/en/'
)->Link )->Link
@ -116,7 +117,8 @@ class DocumentationManifestTests extends SapphireTest
// after sorting, 2 is shown. // after sorting, 2 is shown.
$this->assertContains( $this->assertContains(
'/intermediate/', $this->manifest->getNextPage( '/intermediate/',
$this->manifest->getNextPage(
DOCSVIEWER_PATH . '/tests/docs/en/sort/01-basic.md', DOCSVIEWER_PATH . '/tests/docs/en/sort/01-basic.md',
DOCSVIEWER_PATH . '/tests/docs/en/' DOCSVIEWER_PATH . '/tests/docs/en/'
)->Link )->Link
@ -125,7 +127,8 @@ class DocumentationManifestTests extends SapphireTest
// next gets the following URL // next gets the following URL
$this->assertContains( $this->assertContains(
'/test/', $this->manifest->getNextPage( '/test/',
$this->manifest->getNextPage(
DOCSVIEWER_PATH . '/tests/docs-v2.4/en/index.md', DOCSVIEWER_PATH . '/tests/docs-v2.4/en/index.md',
DOCSVIEWER_PATH . '/tests/docs-v2.4/en/' DOCSVIEWER_PATH . '/tests/docs-v2.4/en/'
)->Link )->Link
@ -145,7 +148,8 @@ class DocumentationManifestTests extends SapphireTest
{ {
// goes right into subfolders // goes right into subfolders
$this->assertContains( $this->assertContains(
'subfolder/subsubfolder/subsubpage', $this->manifest->getPreviousPage( 'subfolder/subsubfolder/subsubpage',
$this->manifest->getPreviousPage(
DOCSVIEWER_PATH . '/tests/docs/en/test.md', DOCSVIEWER_PATH . '/tests/docs/en/test.md',
DOCSVIEWER_PATH . '/tests/docs/en/' DOCSVIEWER_PATH . '/tests/docs/en/'
)->Link )->Link
@ -186,7 +190,7 @@ class DocumentationManifestTests extends SapphireTest
$this->assertDOSContains( $this->assertDOSContains(
$expected, $this->manifest->getChildrenFor( $expected, $this->manifest->getChildrenFor(
DOCSVIEWER_PATH . "/tests/docs/en/" DOCSVIEWER_PATH . '/tests/docs/en/'
) )
); );
@ -197,7 +201,8 @@ class DocumentationManifestTests extends SapphireTest
); );
$this->assertDOSContains( $this->assertDOSContains(
$expected, $this->manifest->getChildrenFor( $expected,
$this->manifest->getChildrenFor(
DOCSVIEWER_PATH . '/tests/docs-v3.0/en/', DOCSVIEWER_PATH . '/tests/docs-v3.0/en/',
DOCSVIEWER_PATH . '/tests/docs-v3.0/en/ChangeLog.md' DOCSVIEWER_PATH . '/tests/docs-v3.0/en/ChangeLog.md'
) )
@ -229,7 +234,7 @@ class DocumentationManifestTests extends SapphireTest
$this->assertEquals(3, $this->manifest->getAllVersionsOfEntity($entity)->count()); $this->assertEquals(3, $this->manifest->getAllVersionsOfEntity($entity)->count());
$entity = $this->manifest->getEntities()->find('Language', 'de'); $entity = $this->manifest->getEntities()->find('Language', 'de');
$this->assertEquals(1, $this->manifest->getAllVersionsOfEntity($entity)->count()); $this->assertEquals(1, $this->manifest->getAllVersionsOfEntity($entity)->count());
} }