From 34d46b7a5b39ae4f44dbccf165fa79c12482adc6 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Sun, 8 Apr 2012 21:23:49 +1200 Subject: [PATCH] MINOR: update references to sapphiredocs to docviewer. ENHANCEMENT: introduce DOCVIEWER_PATH and DOCVIEWER_DIR consts --- README.md | 54 ++----------- _config.php | 12 ++- code/DocumentationParser.php | 11 +-- code/DocumentationPermalinks.php | 19 ++--- code/DocumentationSearch.php | 26 +++++-- code/DocumentationService.php | 31 +++++--- .../DocumentationOpenSearchController.php | 2 +- code/controllers/DocumentationViewer.php | 56 ++++++++------ code/models/DocumentationEntity.php | 6 +- code/models/DocumentationPage.php | 2 +- code/tasks/RebuildLuceneDocsIndex.php | 9 ++- docs/en/Syntax-Highlighting.md | 43 +++++++++++ docs/en/Writing-Documentation.md | 9 +-- docs/en/index.md | 75 ++++++++++++++----- javascript/DocumentationViewer.js | 8 +- templates/DocumentationViewer.ss | 5 -- tests/DocumentTests.yml | 11 --- tests/DocumentationEntityTest.php | 15 ++-- tests/DocumentationPageTest.php | 18 ++--- tests/DocumentationParserTest.php | 42 +++++------ tests/DocumentationSearchTest.php | 6 +- tests/DocumentationServiceTest.php | 18 ++--- tests/DocumentationViewerTest.php | 15 ++-- 23 files changed, 276 insertions(+), 217 deletions(-) create mode 100644 docs/en/Syntax-Highlighting.md delete mode 100755 tests/DocumentTests.yml diff --git a/README.md b/README.md index 9e6daa1..6912aef 100755 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ ## Maintainer Contact * Will Rossiter (Nickname: willr, wrossiter) - + ## Requirements @@ -11,57 +11,13 @@ ## Summary -Reads markdown documentation files from the /docs/ folder in . To read documentation go to yoursite.com/dev/docs/. +Reads text files from a given list of folders from your installation and +provides a web interface for viewing. + +To read documentation go to yoursite.com/dev/docs/ For more documentation on how to use the module please read /docs/Writing-Documentation.md (or via this in /dev/docs/sapphiredocs/Writing-Documentation in your webbrowser) **Note** This module assumes you are using numeric values for your versions. -## Search ## - -Search needs to be indexed manually with `dev/tasks/RebuildLuceneDocsIndex`. - -## Syntax Highlighting ## - -The custom Markdown parser can render custom prefixes for code blocks, -and render it via a [javascript syntax highlighter](http://alexgorbatchev.com/SyntaxHighlighter). - -In: - - :::php - my sourcecode - -Out: - - 
-	my sourcecode
-
- -To include the syntax highlighter source, add the following to your `DocumentationViewer->init()`: - - Requirements::javascript(THIRDPARTY_DIR .'/jquery/jquery.js'); - Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shCore.js'); - Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js'); - Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushPHP.js'); - Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushXML.js'); - // ... any additional syntaxes you want to support - Requirements::combine_files( - 'syntaxhighlighter.js', - array( - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shCore.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushPHP.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushXML.js' - ) - ); - - Requirements::javascript('sapphiredocs/javascript/DocumentationViewer.js'); - - // css - Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shCore.css'); - Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shCoreDefault.css'); - Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shThemeRDark.css'); - -You can overload the `DocumentationViewer` class and add a custom route through `Director::addRule()` -if you prefer not to modify the module file. diff --git a/_config.php b/_config.php index d04cd9e..017b947 100755 --- a/_config.php +++ b/_config.php @@ -1,12 +1,20 @@ no_markup = true; diff --git a/code/DocumentationPermalinks.php b/code/DocumentationPermalinks.php index 9cb1a2d..01f1ec1 100755 --- a/code/DocumentationPermalinks.php +++ b/code/DocumentationPermalinks.php @@ -1,12 +1,12 @@ 'current/en/sapphire/topics/debugging' - * )); + * + * DocumentationPermalinks::add(array( + * 'debugging' => 'current/en/sapphire/topics/debugging' + * )); + * * - * - * You do not need to include the language or the version current as it will add it - * based off the language or version in the session + * Do not need to include the language or the version current as it + * will add it based off the language or version in the session */ public static function add($map = array()) { if(ArrayLib::is_associative($map)) { diff --git a/code/DocumentationSearch.php b/code/DocumentationSearch.php index 2ed7bf8..311ec21 100755 --- a/code/DocumentationSearch.php +++ b/code/DocumentationSearch.php @@ -1,23 +1,27 @@ * yoursite.com/search/?q=Foo&format=rss. // Format can either be specified as rss or left off. * * - * To get a specific amount of results you can also use the modifiers start and limit + * To get a specific amount of results you can also use the modifiers start and + * limit: * * * yoursite.com/search/?q=Foo&start=10&limit=10 * * - * @package sapphiredocs + * @package docviewer */ class DocumentationSearch { @@ -108,7 +112,7 @@ class DocumentationSearch { * * @var string */ - private static $index_location = 'sapphiredocs'; + private static $index_location; /** * Generate an array of every single documentation page installed on the system. @@ -178,7 +182,13 @@ class DocumentationSearch { * @return string */ public function get_index_location() { - return TEMP_FOLDER . '/'. trim(self::$index_location, '/'); + if(!self::$index_location) + self::$index_location = DOCVIEWER_DIR; + + return Controller::join_links( + TEMP_FOLDER, + trim(self::$index_location, '/') + ); } /** diff --git a/code/DocumentationService.php b/code/DocumentationService.php index b647cc7..f9a7b24 100755 --- a/code/DocumentationService.php +++ b/code/DocumentationService.php @@ -4,10 +4,11 @@ * DocumentationService * * Handles the management of the documentation services delivered by the entity. + * * Includes registering which components to document and handles the entities being - * documented + * documented. * - * @package sapphiredocs + * @package docviewer */ class DocumentationService { @@ -28,7 +29,10 @@ class DocumentationService { * * @var array */ - private static $ignored_files = array('.', '..', '.DS_Store', '.svn', '.git', 'assets', 'themes', '_images'); + private static $ignored_files = array( + '.', '..', '.DS_Store', + '.svn', '.git', 'assets', 'themes', '_images' + ); /** * Case insenstive values to use as extensions on markdown pages. The @@ -39,8 +43,12 @@ class DocumentationService { public static $valid_markdown_extensions = array('md', 'txt', 'markdown'); /** - * Registered {@link DocumentationEntity} objects to include in the documentation. - * Either pre-filled by the automatic filesystem parser or via {@link DocumentationService::register()}. + * Registered {@link DocumentationEntity} objects to include in the + * documentation. + * + * Either pre-filled by the automatic filesystem parser or via + * {@link DocumentationService::register()}. + * * Stores the {@link DocumentEntity} objects which contain the languages * and versions of each entity. * @@ -132,8 +140,8 @@ class DocumentationService { } /** - * Return the entities which are listed for documentation. Optionally only get - * entities which have a version or language given + * Return the entities which are listed for documentation. Optionally only + * get entities which have a version or language given. * * @return array */ @@ -157,7 +165,7 @@ class DocumentationService { } /** - * Check to see if a entity is registered with the documenter + * Check to see if a entity is registered with the documenter. * * @param String $entity entity name * @param String $version version @@ -250,7 +258,8 @@ class DocumentationService { } /** - * Register the docs from off a file system if automatic registration is turned on. + * Register the docs from off a file system if automatic registration is + * turned on. * * @see {@link DocumentationService::set_automatic_registration()} */ @@ -294,8 +303,8 @@ class DocumentationService { /** - * Find a documentation page given a path and a file name. It ignores the extensions - * and simply compares the title. + * Find a documentation page given a path and a file name. It ignores the + * extensions and simply compares the title. * * Name may also be a path /install/foo/bar. * diff --git a/code/controllers/DocumentationOpenSearchController.php b/code/controllers/DocumentationOpenSearchController.php index ad68119..cc93810 100644 --- a/code/controllers/DocumentationOpenSearchController.php +++ b/code/controllers/DocumentationOpenSearchController.php @@ -4,7 +4,7 @@ * Public facing controller for handling an opensearch interface based on * the standard search form. * - * @package sapphiredocs + * @package docviewer */ class DocumentationOpenSearchController extends ContentController { diff --git a/code/controllers/DocumentationViewer.php b/code/controllers/DocumentationViewer.php index b64d116..3195606 100755 --- a/code/controllers/DocumentationViewer.php +++ b/code/controllers/DocumentationViewer.php @@ -3,12 +3,13 @@ /** * Documentation Viewer. * - * Reads the bundled markdown files from documentation folders and displays the output (either - * via markdown or plain text) + * Reads the bundled markdown files from documentation folders and displays the + * output (either via markdown or plain text) * - * For more documentation on how to use this class see the documentation in /sapphiredocs/docs folder + * For more documentation on how to use this class see the documentation in the + * docs folder * - * @package sapphiredocs + * @package docviewer */ class DocumentationViewer extends Controller { @@ -34,7 +35,8 @@ class DocumentationViewer extends Controller { /** * The string name of the currently accessed {@link DocumentationEntity} - * object. To access the entire object use {@link getEntity()} + * object. To access the entire object use {@link getEntity()} + * * @var string */ public $entity = ''; @@ -59,41 +61,46 @@ class DocumentationViewer extends Controller { if(!$this->canView()) return Security::permissionFailure($this); - // javascript - Requirements::javascript(THIRDPARTY_DIR .'/jquery/jquery.js'); - + Requirements::javascript(THIRDPARTY_DIR .'/jquery/jquery.js'); Requirements::combine_files( 'syntaxhighlighter.js', array( - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shCore.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushPhp.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushXml.js', - 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushCss.js', - 'sapphiredocs/javascript/shBrushSS.js' + DOCVIEWER_DIR .'/thirdparty/syntaxhighlighter/scripts/shCore.js', + DOCVIEWER_DIR . '/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js', + DOCVIEWER_DIR . '/thirdparty/syntaxhighlighter/scripts/shBrushPhp.js', + DOCVIEWER_DIR . '/thirdparty/syntaxhighlighter/scripts/shBrushXml.js', + DOCVIEWER_DIR . '/thirdparty/syntaxhighlighter/scripts/shBrushCss.js', + DOCVIEWER_DIR . '/javascript/shBrushSS.js' ) ); - Requirements::javascript('sapphiredocs/javascript/DocumentationViewer.js'); - - // css - Requirements::css('sapphiredocs/css/shSilverStripeDocs.css'); + Requirements::javascript(DOCVIEWER_DIR .'/javascript/DocumentationViewer.js'); + Requirements::css(DOCVIEWER_DIR .'/css/shSilverStripeDocs.css'); - Requirements::customScript('jQuery(document).ready(function() {SyntaxHighlighter.all();});'); + Requirements::css(DOCVIEWER_DIR .'/css/DocumentationViewer.css'); } /** - * Can the user view this documentation. Hides all functionality for private wikis + * Can the user view this documentation. Hides all functionality for + * private wikis. * * @return bool */ public function canView() { - return (Director::isDev() || Director::is_cli() || !self::$check_permission || Permission::check(self::$check_permission)); + return (Director::isDev() || Director::is_cli() || + !self::$check_permission || + Permission::check(self::$check_permission) + ); } /** - * Overloaded to avoid "action doesn't exist" errors - all URL parts in this - * controller are virtual and handled through handleRequest(), not controller methods. + * Overloaded to avoid "action doesn't exist" errors - all URL parts in + * this controller are virtual and handled through handleRequest(), not + * controller methods. + * + * @param SS_HTTPRequest + * + * @return SS_HTTPResponse */ public function handleAction($request) { try { @@ -123,7 +130,8 @@ class DocumentationViewer extends Controller { */ public function handleRequest(SS_HTTPRequest $request) { // if we submitted a form, let that pass - if(!$request->isGET() || isset($_GET['action_results'])) return parent::handleRequest($request); + if(!$request->isGET() || isset($_GET['action_results'])) + return parent::handleRequest($request); $firstParam = ($request->param('Action')) ? $request->param('Action') : $request->shift(); $secondParam = $request->shift(); diff --git a/code/models/DocumentationEntity.php b/code/models/DocumentationEntity.php index ee8d75d..943d607 100755 --- a/code/models/DocumentationEntity.php +++ b/code/models/DocumentationEntity.php @@ -13,9 +13,11 @@ * Versions are assumed to be in numeric format (e.g. '2.4'), * * They're also parsed through version_compare() in {@link getStableVersion()} - * which assumes a certain format {@link http://php.net/manual/en/function.version-compare.php} + * which assumes a certain format: * - * @package sapphiredocs + * @see http://php.net/manual/en/function.version-compare.php + * + * @package docviewer * @subpackage models */ diff --git a/code/models/DocumentationPage.php b/code/models/DocumentationPage.php index df83c29..3328daa 100755 --- a/code/models/DocumentationPage.php +++ b/code/models/DocumentationPage.php @@ -4,7 +4,7 @@ * A specific page within a {@link DocumentationEntity}. Maps 1 to 1 to a file on the * filesystem. * - * @package sapphiredocs + * @package docviewer * @subpackage model */ class DocumentationPage extends ViewableData { diff --git a/code/tasks/RebuildLuceneDocsIndex.php b/code/tasks/RebuildLuceneDocsIndex.php index 21f879d..945a355 100755 --- a/code/tasks/RebuildLuceneDocsIndex.php +++ b/code/tasks/RebuildLuceneDocsIndex.php @@ -5,7 +5,7 @@ * * For the hourly cron rebuild use RebuildLuceneDocusIndex_Hourly * - * @package sapphiredocs + * @package docviewer * @subpackage tasks */ @@ -13,14 +13,15 @@ class RebuildLuceneDocsIndex extends BuildTask { protected $title = "Rebuild Documentation Search Indexes"; - protected $description = "Rebuilds the indexes used for the search engine in sapphiredocs. Gathers all documentation files from your modules"; + protected $description = " + Rebuilds the indexes used for the search engine in the docviewer."; function run($request) { $this->rebuildIndexes(); } function rebuildIndexes($quiet = false) { - require_once(BASE_PATH . '/sapphiredocs/thirdparty/markdown/markdown.php'); + require_once(DOCVIEWER_PATH .'/thirdparty/markdown/markdown.php'); require_once 'Zend/Search/Lucene.php'; ini_set("memory_limit", -1); @@ -106,7 +107,7 @@ class RebuildLuceneDocsIndex extends BuildTask { } /** - * @package sapphiredocs + * @package docviewer * @subpackage tasks */ class RebuildLuceneDocusIndex_Hourly extends HourlyTask { diff --git a/docs/en/Syntax-Highlighting.md b/docs/en/Syntax-Highlighting.md new file mode 100644 index 0000000..5d361f3 --- /dev/null +++ b/docs/en/Syntax-Highlighting.md @@ -0,0 +1,43 @@ +# Syntax Highlighting + +The custom Markdown parser can render custom prefixes for code blocks, and +render it via a [javascript syntax highlighter](http://alexgorbatchev.com/SyntaxHighlighter). + +In: + + :::php + my sourcecode + +Out: + + 
+	my sourcecode
+
+ +To include the syntax highlighter source, add the following to your `DocumentationViewer->init()`: + + Requirements::javascript(THIRDPARTY_DIR .'/jquery/jquery.js'); + Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shCore.js'); + Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js'); + Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushPHP.js'); + Requirements::javascript('sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushXML.js'); + // ... any additional syntaxes you want to support + Requirements::combine_files( + 'syntaxhighlighter.js', + array( + 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shCore.js', + 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushJScript.js', + 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushPHP.js', + 'sapphiredocs/thirdparty/syntaxhighlighter/scripts/shBrushXML.js' + ) + ); + + Requirements::javascript('sapphiredocs/javascript/DocumentationViewer.js'); + + // css + Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shCore.css'); + Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shCoreDefault.css'); + Requirements::css('sapphiredocs/thirdparty/syntaxhighlighter/styles/shThemeRDark.css'); + +You can overload the `DocumentationViewer` class and add a custom route through `Director::addRule()` +if you prefer not to modify the module file. diff --git a/docs/en/Writing-Documentation.md b/docs/en/Writing-Documentation.md index 21e2acb..d1507f8 100755 --- a/docs/en/Writing-Documentation.md +++ b/docs/en/Writing-Documentation.md @@ -1,11 +1,7 @@ # Writing Documentation -Your documentation needs to go in the specific modules docs folder which it -refers mostly too. For example if you want to document a feature of your -custom module 'mymodule' you need to create markdown files in mymodule/docs/en/. - -The files have to end with the __.md__ extension. The documentation viewer will -automatically replace hyphens (-) with spaces. +The files have to end with the __.md__ or __.markdown__ extension. The +documentation viewer will automatically replace hyphens (-) with spaces. my-documentation-file.md @@ -60,7 +56,6 @@ default behaviour is to display an ordered list of links. The table of contents on each module page is generated based on where and what headers you use. - ## Images and Files If you want to attach images and other assets to a page you need to bundle those diff --git a/docs/en/index.md b/docs/en/index.md index 8ebdc12..a15ec20 100755 --- a/docs/en/index.md +++ b/docs/en/index.md @@ -1,38 +1,79 @@ -# Sapphire Documentation Module +# Docviewer Module -This module has been developed to read and display content from markdown files in webbrowser. It is an easy -way to bundle end user documentation within a SilverStripe installation. - -See [Writing Documentation](dev/docs/en/sapphiredocs/writing-documentation) for more information on how to write markdown files which -are available here. - -To include your docs file here create a __docs/en/index.md__ file. You can also include custom paths and versions. To configure the documentation system the configuration information is available on the [Configurations](dev/docs/en/sapphiredocs/configuration-options) -page. +This module has been developed to read and display content from markdown and +plain text files in web browser. It provides an easy way to bundle end user +documentation within a SilverStripe installation or module. ## Setup -### Enabling Search +The module includes the ability to read documentation from any folder on your +file system. By standard, documentation should go in a __docs__ folder in the +root of your module or project documentation. -The module provides automatic search functionality via [Lucene Search](http://lucene.apache.org/java/docs/index.html). To enable search -you need to add the following to your applications _config.php file: +### Standard + +If you follow the standard setup create a file in /<>/__docs/_en/index.md__ +file then include the following in your config file: + + DocumentationService::set_automatic_registration(true); + +Now visit yoursite.com/dev/docs you should see your module. + +### Custom Folders + +If you wish to register specific folders only, or folders in a non standard +location then you can register paths directly: + + try { + DocumentationService::register( + $name = "sapphire", + $path = "/src/sapphire_master/docs/", + $version = 'trunk' + ); + } catch(InvalidArgumentException $e) { + // Silence if path is not found (for CI environment) + } + + +To configure the documentation system the configuration information is +available on the [Configurations](dev/docs/en/docviewer/configuration-options) +page. + +## Writing documentation + +See [Writing Documentation](dev/docs/en/sapphiredocs/writing-documentation) +for more information on how to write markdown files which are available here. + + +## Enabling Search + +The module provides automatic search functionality via [Lucene Search](http://lucene.apache.org/java/docs/index.html). + +To enable search you need to add the following to your applications _config.php +file: DocumentationSearch::enable(); -After adding that line you will also need to build the indexes of the search. You can do this either via your web browser by accessing +After adding that line you will also need to build the indexes of the search. + +You can do this either via your web browser by accessing http://yoursite.com/dev/tasks/RebuildLuceneDocsIndex?flush=1 -Or rebuild it via sake. You will want to set this up as a cron job if your documentation search needs to be updated on the fly +Or rebuild it via sake. You will want to set this up as a cron job if your +documentation search needs to be updated on the fly sake dev/tasks/RebuildLuceneDocsIndex flush=1 -### Using a URL other than /dev/docs/ +## Using a URL other than /dev/docs/ -By default, the documentation is available in `dev/docs`. If you want it to live on the webroot instead of a subfolder, -add the following configuration to your. +By default, the documentation is available in `dev/docs`. If you want it to +live on the webroot instead of a subfolder or on another url address, add the +following configuration to your _config.php file: DocumentationViewer::set_link_base(''); + Director::addRules(1, array( '$Action' => 'DocumentationViewer', '' => 'DocumentationViewer' diff --git a/javascript/DocumentationViewer.js b/javascript/DocumentationViewer.js index 05294cc..e0100aa 100755 --- a/javascript/DocumentationViewer.js +++ b/javascript/DocumentationViewer.js @@ -1,4 +1,4 @@ -(function($) { +;(function($) { $(document).ready(function() { /** ----------------------------------------------- @@ -52,8 +52,8 @@ $("#Form_LanguageForm select").change(function() { $("#Form_LanguageForm").submit(); }); + + SyntaxHighlighter.defaults.toolbar = false; + SyntaxHighlighter.all(); }); - - // Syntaxhighlighter defaults - SyntaxHighlighter.defaults.toolbar = false; })(jQuery); diff --git a/templates/DocumentationViewer.ss b/templates/DocumentationViewer.ss index 664a4b9..e311fc5 100755 --- a/templates/DocumentationViewer.ss +++ b/templates/DocumentationViewer.ss @@ -5,11 +5,6 @@ <% base_tag %> SilverStripe Documentation - - <% require themedCSS(DocumentationViewer) %> - <% require javascript(sapphire/thirdparty/jquery/jquery.js) %> - <% require javascript(sapphiredocs/javascript/DocumentationViewer.js) %> - diff --git a/tests/DocumentTests.yml b/tests/DocumentTests.yml deleted file mode 100755 index 4ad6b98..0000000 --- a/tests/DocumentTests.yml +++ /dev/null @@ -1,11 +0,0 @@ -Permission: - admin: - Code: ADMIN -Group: - admins: - Code: admins - Permissions: =>Permission.admin -Member: - admin: - Email: admin@test.com - Groups: =>Group.admins \ No newline at end of file diff --git a/tests/DocumentationEntityTest.php b/tests/DocumentationEntityTest.php index 3eb2bbc..eb4482c 100755 --- a/tests/DocumentationEntityTest.php +++ b/tests/DocumentationEntityTest.php @@ -1,11 +1,12 @@ assertEquals($entity->getTitle(), 'My Test'); $this->assertEquals($entity->getVersions(), array('1.0')); @@ -20,13 +21,13 @@ class DocumentationEntityTest extends SapphireTest { } function testgetStableVersion() { - $entity = new DocumentationEntity('docs', '1.0', '../sapphiredocs/tests/docs/', 'My Test'); - $entity->addVersion('1.1', '../sapphiredocs/tests/docs-v2.4/'); - $entity->addVersion('0.0', '../sapphiredocs/tests/docs-v3.0/'); + $entity = new DocumentationEntity('docs', '1.0', DOCVIEWER_PATH. '/tests/docs/', 'My Test'); + $entity->addVersion('1.1', DOCVIEWER_PATH. '/tests/docs-v2.4/'); + $entity->addVersion('0.0', DOCVIEWER_PATH. '/tests/docs-v3.0/'); $this->assertEquals('1.1', $entity->getStableVersion(), 'Automatic version sorting'); - $entity = new DocumentationEntity('docs', '1.0', '../sapphiredocs/tests/docs/', 'My Test'); - $entity->addVersion('1.1.', '../sapphiredocs/tests/docs-v2.4/'); + $entity = new DocumentationEntity('docs', '1.0', DOCVIEWER_PATH. '/tests/docs/', 'My Test'); + $entity->addVersion('1.1.', DOCVIEWER_PATH .'/tests/docs-v2.4/'); $entity->setStableVersion('1.0'); $this->assertEquals('1.0', $entity->getStableVersion(), 'Manual setting'); } diff --git a/tests/DocumentationPageTest.php b/tests/DocumentationPageTest.php index ef85a63..d905ebd 100755 --- a/tests/DocumentationPageTest.php +++ b/tests/DocumentationPageTest.php @@ -1,14 +1,14 @@ setRelativePath('test.md'); @@ -32,8 +32,8 @@ class DocumentationPageTest extends SapphireTest { $this->assertStringEndsWith('testmodule/en/subfolder/subpage', $nested->Link()); // test with version. - $entity = DocumentationService::register("versionlinks", BASE_PATH . "/sapphiredocs/tests/docs-v2.4/", '1'); - $entity->addVersion('2', BASE_PATH . "/sapphiredocs/tests/docs-v3.0/"); + $entity = DocumentationService::register("versionlinks", DOCVIEWER_PATH ."/tests/docs-v2.4/", '1'); + $entity->addVersion('2', DOCVIEWER_PATH ."/tests/docs-v3.0/"); $entity->setStableVersion('2'); $page = new DocumentationPage(); @@ -47,19 +47,19 @@ class DocumentationPageTest extends SapphireTest { function testGetRelativePath() { $page = new DocumentationPage(); $page->setRelativePath('test.md'); - $page->setEntity(new DocumentationEntity('mymodule', null, BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', null, DOCVIEWER_PATH . '/tests/docs/')); $this->assertEquals('test.md', $page->getRelativePath()); $page = new DocumentationPage(); $page->setRelativePath('subfolder/subpage.md'); - $page->setEntity(new DocumentationEntity('mymodule', null, BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', null, DOCVIEWER_PATH . '/tests/docs/')); $this->assertEquals('subfolder/subpage.md', $page->getRelativePath()); } function testGetPath() { - $absPath = BASE_PATH . '/sapphiredocs/tests/docs/'; + $absPath = DOCVIEWER_PATH .'/tests/docs/'; $page = new DocumentationPage(); $page->setRelativePath('test.md'); $page->setEntity(new DocumentationEntity('mymodule', null, $absPath)); @@ -74,7 +74,7 @@ class DocumentationPageTest extends SapphireTest { } function testGetBreadcrumbTitle() { - $entity = new DocumentationEntity('testmodule', null, BASE_PATH . '/sapphiredocs/tests/docs/'); + $entity = new DocumentationEntity('testmodule', null, DOCVIEWER_PATH . '/tests/docs/'); $page = new DocumentationPage(); $page->setRelativePath('test.md'); @@ -84,7 +84,7 @@ class DocumentationPageTest extends SapphireTest { $page = new DocumentationPage(); $page->setRelativePath('subfolder/subpage.md'); - $page->setEntity(new DocumentationEntity('mymodule', null, BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', null, DOCVIEWER_PATH . '/tests/docs/')); $this->assertEquals('Mymodule - Subfolder - Subpage', $page->getBreadcrumbTitle()); } diff --git a/tests/DocumentationParserTest.php b/tests/DocumentationParserTest.php index c7d9707..771ca53 100755 --- a/tests/DocumentationParserTest.php +++ b/tests/DocumentationParserTest.php @@ -1,13 +1,13 @@ setRelativePath('test.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $page->setLang('en'); $page->setVersion('2.4'); $result = DocumentationParser::rewrite_code_blocks($page->getMarkdown()); @@ -38,24 +38,24 @@ HTML; // Page on toplevel $page = new DocumentationPage(); $page->setRelativePath('subfolder/subpage.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $page->setLang('en'); $page->setVersion('2.4'); $result = DocumentationParser::rewrite_image_links($page->getMarkdown(), $page, 'mycontroller/cms/2.4/en/'); $this->assertContains( - '[relative image link](' . Director::absoluteBaseURL() . '/sapphiredocs/tests/docs/en/subfolder/_images/image.png)', + '[relative image link](' . Director::absoluteBaseURL() .'/'. DOCVIEWER_DIR . '/tests/docs/en/subfolder/_images/image.png)', $result ); $this->assertContains( - '[parent image link](' . Director::absoluteBaseURL() . '/sapphiredocs/tests/docs/en/_images/image.png)', + '[parent image link](' . Director::absoluteBaseURL() . '/'. DOCVIEWER_DIR. '/tests/docs/en/_images/image.png)', $result ); - // TODO Fix absolute image references + // $this->assertContains( - // '[absolute image link](' . Director::absoluteBaseURL() . '/sapphiredocs/tests/docs/en/_images/image.png)', - // $result + // '[absolute image link](' . Director::absoluteBaseURL() . '/'. DOCVIEWER_DIR. '/tests/docs/en/_images/image.png)', + // $result // ); } @@ -63,7 +63,7 @@ HTML; // Page on toplevel $page = new DocumentationPage(); $page->setRelativePath('test.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH .'/tests/docs/')); $page->setLang('en'); $page->setVersion('2.4'); @@ -81,7 +81,7 @@ HTML; function testHeadlineAnchors() { $page = new DocumentationPage(); $page->setRelativePath('test.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $page->setLang('en'); $page->setVersion('2.4'); @@ -119,7 +119,7 @@ HTML; // Page on toplevel $page = new DocumentationPage(); $page->setRelativePath('test.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $result = DocumentationParser::rewrite_relative_links($page->getMarkdown(), $page, 'mycontroller/cms/2.4/en/'); @@ -147,7 +147,7 @@ HTML; // Page in subfolder $page = new DocumentationPage(); $page->setRelativePath('subfolder/subpage.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $result = DocumentationParser::rewrite_relative_links($page->getMarkdown(), $page, 'mycontroller/cms/2.4/en/'); @@ -180,7 +180,7 @@ HTML; // Page in nested subfolder $page = new DocumentationPage(); $page->setRelativePath('subfolder/subsubfolder/subsubpage.md'); - $page->setEntity(new DocumentationEntity('mymodule', '2.4', BASE_PATH . '/sapphiredocs/tests/docs/')); + $page->setEntity(new DocumentationEntity('mymodule', '2.4', DOCVIEWER_PATH . '/tests/docs/')); $result = DocumentationParser::rewrite_relative_links($page->getMarkdown(), $page, 'mycontroller/cms/2.4/en/'); @@ -209,7 +209,7 @@ HTML; function testRetrieveMetaData() { $page = new DocumentationPage(); $page->setRelativePath('MetaDataTest.md'); - $page->setEntity(new DocumentationEntity('parser', '2.4', BASE_PATH . '/sapphiredocs/tests/docs-parser/')); + $page->setEntity(new DocumentationEntity('parser', '2.4', DOCVIEWER_PATH . '/tests/docs-parser/')); DocumentationParser::retrieve_meta_data($page); @@ -221,9 +221,9 @@ HTML; function testParserConvertsSpecialCharacters() { $page = new DocumentationPage(); $page->setRelativePath('CodeSnippets.md'); - $page->setEntity(new DocumentationEntity('parser', '2.4', BASE_PATH . '/sapphiredocs/tests/docs-parser/')); + $page->setEntity(new DocumentationEntity('parser', '2.4', DOCVIEWER_PATH . '/tests/docs-parser/')); - $parsed = DocumentationParser::parse($page, '/sapphiredocs/tests/docs-parser/'); + $parsed = DocumentationParser::parse($page, '/'.DOCVIEWER_DIR .'/tests/docs-parser/'); // header elements parsed $this->assertContains( @@ -239,21 +239,21 @@ HTML; } function testRewritingRelativeLinksToFiles() { - $folder = '/sapphiredocs/tests/docs-parser/'; + $folder = DOCVIEWER_PATH . '/tests/docs-parser/'; $page = new DocumentationPage(); $page->setRelativePath('file-download.md'); - $page->setEntity(new DocumentationEntity('parser', '2.4', BASE_PATH . $folder)); + $page->setEntity(new DocumentationEntity('parser', '2.4', $folder)); $parsed = DocumentationParser::parse($page, $folder); - + $this->assertContains( - Controller::join_links($folder, '/en/_images/external_link.png'), + DOCVIEWER_DIR .'/tests/docs-parser/en/_images/external_link.png', $parsed ); $this->assertContains( - Controller::join_links($folder, '/en/_images/test.tar.gz'), + DOCVIEWER_DIR .'/tests/docs-parser/en/_images/test.tar.gz', $parsed ); } diff --git a/tests/DocumentationSearchTest.php b/tests/DocumentationSearchTest.php index 2cbba3e..50ecd69 100755 --- a/tests/DocumentationSearchTest.php +++ b/tests/DocumentationSearchTest.php @@ -1,7 +1,7 @@ assertContains('index.md', $pages->column('Filename'), 'The tests/docs/en folder should contain a index file'); @@ -28,7 +28,7 @@ class DocumentationServiceTest extends SapphireTest { function testGetPagesFromFolderRecursive() { - $entity = DocumentationService::register('testdocsrecursive', BASE_PATH . '/sapphiredocs/tests/docs-recursive/'); + $entity = DocumentationService::register('testdocsrecursive', DOCVIEWER_PATH . '/tests/docs-recursive/'); $pages = DocumentationService::get_pages_from_folder($entity, null, true); @@ -43,19 +43,19 @@ class DocumentationServiceTest extends SapphireTest { } function testFindPath() { - DocumentationService::register("DocumentationViewerTests", BASE_PATH . "/sapphiredocs/tests/docs/"); + DocumentationService::register("DocumentationViewerTests", DOCVIEWER_PATH . "/tests/docs/"); // file $path = DocumentationService::find_page('DocumentationViewerTests', array('test')); - $this->assertEquals(BASE_PATH . "/sapphiredocs/tests/docs/en/test.md", $path); + $this->assertEquals(DOCVIEWER_PATH . "/tests/docs/en/test.md", $path); // the home page. The path finder should go to the index.md file in the default language $path = DocumentationService::find_page('DocumentationViewerTests', array('')); - $this->assertEquals(BASE_PATH . "/sapphiredocs/tests/docs/en/index.md", $path); + $this->assertEquals(DOCVIEWER_PATH . "/tests/docs/en/index.md", $path); // second level $path = DocumentationService::find_page('DocumentationViewerTests', array('subfolder', 'subpage')); - $this->assertEquals(BASE_PATH . "/sapphiredocs/tests/docs/en/subfolder/subpage.md", $path); + $this->assertEquals(DOCVIEWER_PATH . "/tests/docs/en/subfolder/subpage.md", $path); // subsubfolder has no index file. It should fail instead the viewer should pick up on this // and display the listing of the folder @@ -64,11 +64,11 @@ class DocumentationServiceTest extends SapphireTest { // third level $path = DocumentationService::find_page('DocumentationViewerTests', array('subfolder', 'subsubfolder', 'subsubpage')); - $this->assertEquals(BASE_PATH . "/sapphiredocs/tests/docs/en/subfolder/subsubfolder/subsubpage.md", $path); + $this->assertEquals(DOCVIEWER_PATH . "/tests/docs/en/subfolder/subsubfolder/subsubpage.md", $path); // with trailing slash $path = DocumentationService::find_page('DocumentationViewerTests', array('subfolder', 'subsubfolder', 'subsubpage')); - $this->assertEquals(BASE_PATH . "/sapphiredocs/tests/docs/en/subfolder/subsubfolder/subsubpage.md", $path); + $this->assertEquals(DOCVIEWER_PATH . "/tests/docs/en/subfolder/subsubfolder/subsubpage.md", $path); } diff --git a/tests/DocumentationViewerTest.php b/tests/DocumentationViewerTest.php index c7d9541..257fc77 100755 --- a/tests/DocumentationViewerTest.php +++ b/tests/DocumentationViewerTest.php @@ -4,13 +4,12 @@ * Some of these tests are simply checking that pages load. They should not assume * somethings working. * - * @package sapphiredocs + * @package docviewer + * @subpackage tests */ class DocumentationViewerTest extends FunctionalTest { - static $fixture_file = 'sapphiredocs/tests/DocumentTests.yml'; - protected $autoFollowRedirection = false; function setUpOnce() { @@ -26,12 +25,12 @@ class DocumentationViewerTest extends FunctionalTest { } // We set 3.0 as current, and test most assertions against 2.4 - to avoid 'current' rewriting issues - DocumentationService::register("DocumentationViewerTests", BASE_PATH . "/sapphiredocs/tests/docs/", '2.3'); - DocumentationService::register("DocumentationViewerTests", BASE_PATH . "/sapphiredocs/tests/docs-v2.4/", '2.4', 'Doc Test', true); - DocumentationService::register("DocumentationViewerTests", BASE_PATH . "/sapphiredocs/tests/docs-v3.0/", '3.0', 'Doc Test'); + DocumentationService::register("DocumentationViewerTests", DOCVIEWER_PATH . "/tests/docs/", '2.3'); + DocumentationService::register("DocumentationViewerTests", DOCVIEWER_PATH . "/tests/docs-v2.4/", '2.4', 'Doc Test', true); + DocumentationService::register("DocumentationViewerTests", DOCVIEWER_PATH . "/tests/docs-v3.0/", '3.0', 'Doc Test'); - DocumentationService::register("DocumentationViewerAltModule1", BASE_PATH . "/sapphiredocs/tests/docs-parser/", '1.0'); - DocumentationService::register("DocumentationViewerAltModule2", BASE_PATH . "/sapphiredocs/tests/docs-search/", '1.0'); + DocumentationService::register("DocumentationViewerAltModule1", DOCVIEWER_PATH . "/tests/docs-parser/", '1.0'); + DocumentationService::register("DocumentationViewerAltModule2", DOCVIEWER_PATH . "/tests/docs-search/", '1.0'); } function tearDownOnce() {