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

Kill DocumentationService in favour of config API.

Browse Source 
This continues on the migration to the Manifest. Instead of using calls to a `Service` now all file related lookups are done through the `DocumentationManifest`
This commit is contained in:
Will Rossiter 2014-09-07 17:09:28 +12:00
parent 43b6d42719
commit 0b91b91e33
20 changed files with 337 additions and 499 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_config/docsviewer.yml
View File

@ -3,4 +3,6 @@ name: docsviewer
--- ---
DocumentationViewer: DocumentationViewer:
google_analytics_code: '' google_analytics_code: ''
DocumentationManifest:
automatic_registration: true

50
code/DocumentationHelper.php
View File

@ -7,41 +7,6 @@
*/ */
class DocumentationHelper { class DocumentationHelper {
/**
* Generate an array of every single documentation page installed on the
* system.
*
* @return ArrayList
*/
public static function get_all_documentation_pages() {
DocumentationService::load_automatic_registration();
$modules = DocumentationService::get_registered_entities();
$output = new ArrayList();
if($modules) {
foreach($modules as $module) {
foreach($module->getVersions() as $version) {
try {
$pages = DocumentationService::get_pages_from_folder($module, false, true, $version);
if($pages) {
foreach($pages as $page) {
$output->push($page);
}
}
}
catch(Exception $e) {
user_error($e, E_USER_WARNING);
}
}
}
}
return $output;
}
/** /**
* String helper for cleaning a file name to a readable version. * String helper for cleaning a file name to a readable version.
* *
@ -108,4 +73,19 @@ class DocumentationHelper {
return $name; return $name;
} }
/**
* Helper function to get the extension of the filename.
*
* @param string
*
* @return string
*/
public static function get_extension($name) {
if(strrpos($name,'.') !== false) {
return substr($name, strrpos($name,'.') + 1);
}
return null;
}
} }

116
code/DocumentationManifest.php
View File

@ -31,6 +31,20 @@ class DocumentationManifest {
const TEMPLATES_DIR = 'documentation'; const TEMPLATES_DIR = 'documentation';
/**
* @config
*
* @var boolean $automatic_registration
*/
private static $automatic_registration = true;
/**
* @config
*
* @var array $registered_entities
*/
private static $register_entities = array();
protected $base; protected $base;
protected $cache; protected $cache;
protected $cacheKey; protected $cacheKey;
@ -40,6 +54,11 @@ class DocumentationManifest {
private $entity; private $entity;
/**
* @var array
*/
private $registeredEntities = array();
/** /**
* Constructs a new template manifest. The manifest is not actually built * Constructs a new template manifest. The manifest is not actually built
* or loaded from cache until needed. * or loaded from cache until needed.
@ -48,6 +67,7 @@ class DocumentationManifest {
* @param bool $forceRegen Force the manifest to be regenerated. * @param bool $forceRegen Force the manifest to be regenerated.
*/ */
public function __construct($forceRegen = false) { public function __construct($forceRegen = false) {
$this->setupEntities();
$this->cacheKey = 'manifest'; $this->cacheKey = 'manifest';
$this->forceRegen = $forceRegen; $this->forceRegen = $forceRegen;
@ -57,6 +77,93 @@ class DocumentationManifest {
)); ));
} }
/**
* Sets up the top level entities.
*
* Either manually registered through the YAML syntax or automatically
* loaded through investigating the file system for `docs` folder.
*/
public function setupEntities() {
if(Config::inst()->get('DocumentationManifest', 'automatic_registration')) {
$this->populateEntitiesFromInstall();
}
$registered = Config::inst()->get('DocumentationManifest', 'register_entities');
foreach($registered as $details) {
// validate the details provided through the YAML configuration
$required = array('Path', 'Version', 'Title');
foreach($required as $require) {
if(!isset($details[$require])) {
throw new Exception("$require is a required key in DocumentationManifest.register_entities");
}
}
if(isset($this->registeredEntities[$details['Title']])) {
$entity = $this->registeredEntities[$details['Title']];
} else {
$entity = new DocumentationEntity(
$details['Path'],
$details['Title']
);
$this->registeredEntities[$details['Title']] = $entity;
}
$version = new DocumentationEntityVersion(
$entity,
Controller::join_links(BASE_PATH, $details['Path']),
$details['Version'],
(isset($details['Stable'])) ? $details['Stable'] : false
);
$entity->addVersion($version);
}
}
/**
* @return array
*/
public function getEntities() {
return $this->registeredEntities;
}
/**
* Scans the current installation and picks up all the SilverStripe modules
* that contain a `docs` folder.
*
* @return void
*/
public function populateEntitiesFromInstall() {
$entities = array();
foreach(scandir(BASE_PATH) as $key => $entity) {
if($key == "themes") {
continue;
}
$dir = is_dir(Controller::join_links(BASE_PATH, $entity));
if($dir) {
// check to see if it has docs
$docs = Controller::join_links($dir, 'docs');
if(is_dir($docs)) {
$entities[] = array(
'BasePath' => $entity,
'Folder' => $key,
'Version' => 'master',
'Stable' => true
);
}
}
}
Config::inst()->update(
'DocumentationManifest', 'registered_entities', $entities
);
}
/** /**
* *
@ -91,16 +198,16 @@ class DocumentationManifest {
*/ */
public function getPage($url) { public function getPage($url) {
$pages = $this->getPages(); $pages = $this->getPages();
$url = rtrim($url, '/') . '/';
if(!isset($pages[$url])) { if(!isset($pages[$url])) {
return null; return null;
} }
$record = $pages[$url]; $record = $pages[$url];
DocumentationService::load_automatic_registration(); foreach($this->getEntities() as $entity) {
foreach(DocumentationService::get_registered_entities() as $entity) {
foreach($entity->getVersions() as $version) { foreach($entity->getVersions() as $version) {
foreach($version->getSupportedLanguages() as $language) { foreach($version->getSupportedLanguages() as $language) {
if(strpos($record['filepath'], $language->getPath()) !== false) { if(strpos($record['filepath'], $language->getPath()) !== false) {
@ -130,8 +237,7 @@ class DocumentationManifest {
'file_callback' => array($this, 'handleFile') 'file_callback' => array($this, 'handleFile')
)); ));
DocumentationService::load_automatic_registration(); foreach($this->getEntities() as $entity) {
foreach(DocumentationService::get_registered_entities() as $entity) {
foreach($entity->getVersions() as $version) { foreach($entity->getVersions() as $version) {
foreach($version->getSupportedLanguages() as $k => $v) { foreach($version->getSupportedLanguages() as $k => $v) {

198
code/DocumentationService.php
View File

@ -1,198 +0,0 @@
<?php
/**
* DocumentationService
*
* Handles the management of the documentation services delivered by the entity.
*
* Includes registering which components to document and handles the entities
* being documented.
*
* @package docsviewer
*/
class DocumentationService {
/**
* 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.
*
* You can remove registered {@link DocumentationEntity} objects by using
* {@link DocumentationService::unregister()}
*
* @var array
*/
private static $registered_entities = array();
/**
* Should generation of documentation categories be automatic?
*
* If this is set to true then it will generate {@link DocumentationEntity}
* objects from the filesystem. This can be slow and also some projects
* may want to restrict to specific project folders (rather than everything).
*
* You can also disable or remove a given folder from registration using
* {@link DocumentationService::unregister()}
*
* @see DocumentationService::$registered_entities
* @see DocumentationService::set_automatic_registration();
*
* @var bool
*/
private static $automatic_registration = true;
/**
* Set automatic registration of entities and documentation folders
*
* @see DocumentationService::$automatic_registration
* @param bool
*/
public static function set_automatic_registration($bool = true) {
self::$automatic_registration = $bool;
if(!$bool) {
// remove current registed entities when disabling automatic
// registration needed to avoid caching issues when running all the
// tests
self::$registered_entities = array();
}
}
/**
* Is automatic registration of entities enabled.
*
* @return bool
*/
public static function automatic_registration_enabled() {
return self::$automatic_registration;
}
/**
* Return the entities which are listed for documentation. Optionally only
* get entities which have a version or language given.
*
* @return array
*/
public static function get_registered_entities($version = false, $lang = false) {
$output = array();
if($entities = self::$registered_entities) {
if($version || $lang) {
foreach($entities as $entity) {
if(self::is_registered_entity($entity->getFolder(), $version, $lang)) {
$output[$entity->getFolder()] = $entity;
}
}
}
else {
$output = $entities;
}
}
return $output;
}
/**
* Register a entity to be included in the documentation. To unregister a
* entity use {@link DocumentationService::unregister()}.
*
* @param string $entity Name of entity to register
* @param string $path Path to documentation root.
* @param float $version Version of entity.
* @param string $title Nice title to use
* @param bool $latest - return is this the latest release.
*
* @throws InvalidArgumentException
*
* @return DocumentationEntity
*/
public static function register($entity, $path, $version = '', $title = false, $latest = false) {
if(!file_exists($path)) {
throw new InvalidArgumentException(sprintf('Path "%s" doesn\'t exist', $path));
}
// add the entity to the registered array
if(!isset(self::$registered_entities[$entity])) {
$de = new DocumentationEntity($entity, $title);
self::$registered_entities[$entity] = $de;
}
else {
// entity exists so add the version to it
$de = self::$registered_entities[$entity];
}
// create a new version of the entity and attach it the the entity
$dve = new DocumentationEntityVersion($de, $path, $version, $latest);
$de->addVersion($dve);
return $de;
}
/**
* Unregister a entity from being included in the documentation. Useful
* for keeping {@link DocumentationService::$automatic_registration} enabled
* but disabling entities which you do not want to show. Combined with a
* {@link Director::isLive()} you can hide entities you don't want a client
* to see.
*
* If no version or lang specified then the whole entity is removed.
* Otherwise only the specified version of the documentation.
*
* @param string $entity
* @param string $version
*
* @return bool
*/
public static function unregister($entityName, $version = false) {
if(isset(self::$registered_entities[$entityName])) {
$entity = self::$registered_entities[$entityName];
if($version) {
$entity->removeVersion($version);
} else {
unset(self::$registered_entities[$entityName]);
}
return true;
}
return false;
}
/**
* Register the docs from off a file system if automatic registration is
* turned on.
*
* @see {@link DocumentationService::set_automatic_registration()}
*/
public static function load_automatic_registration() {
if(!self::automatic_registration_enabled()) {
return;
}
$entities = scandir(BASE_PATH);
if($entities) {
foreach($entities as $key => $entity) {
$dir = is_dir(Controller::join_links(BASE_PATH, $entity));
if($dir) {
// check to see if it has docs
$docs = Director::baseFolder() . '/' . Controller::join_links($entity, 'docs');
if(is_dir($docs)) {
self::register($entity, $docs, 'current', $entity, true);
}
}
}
}
}
}

2
code/controllers/DocumentationSearchController.php
View File

@ -87,8 +87,6 @@ class DocumentationSearchController extends DocumentationViewer {
* @return Form * @return Form
*/ */
public function AdvancedSearchForm() { public function AdvancedSearchForm() {
$entities = DocumentationService::get_registered_entities();
return new DocumentationAdvancedSearchForm($this); return new DocumentationAdvancedSearchForm($this);
} }

114
code/controllers/DocumentationViewer.php
View File

@ -14,6 +14,13 @@
class DocumentationViewer extends Controller { class DocumentationViewer extends Controller {
/**
* @var array
*/
private static $extensions = array(
'DocumentationViewerVersionWarning'
);
/** /**
* @var array * @var array
*/ */
@ -245,30 +252,25 @@ class DocumentationViewer extends Controller {
* @return DataObject * @return DataObject
*/ */
public function getEntities() { public function getEntities() {
$entities = DocumentationService::get_registered_entities(); $entities = $this->getManifest()->getEntities();
$output = new ArrayList(); $output = new ArrayList();
$currentEntity = $this->getEntity();
if($entities) { if($entities) {
foreach($entities as $entity) { foreach($entities as $entity) {
$mode = ($entity === $currentEntity) ? 'current' : 'link'; $mode = 'link';
$folder = $entity->getFolder();
if($this->record) {
if($entity->hasRecord($this->record)) {
$mode = 'current';
}
}
$link = $entity->Link(); $link = $entity->Link();
$content = false;
// if($page = $entity->getIndexPage()) {
// $content = DBField::create_field('HTMLText', DocumentationParser::parse($page, $link));
// }
$output->push(new ArrayData(array( $output->push(new ArrayData(array(
'Title' => $entity->getTitle(), 'Title' => $entity->getTitle(),
'Link' => $link, 'Link' => $link,
'LinkingMode' => $mode, 'LinkingMode' => $mode
'Content' => $content,
))); )));
} }
} }
@ -276,23 +278,6 @@ class DocumentationViewer extends Controller {
return $output; return $output;
} }
/**
* Get the currently accessed entity from the site.
*
* @return DocumentationEntity
*/
public function getEntity() {
if($this->entity) {
return DocumentationService::is_registered_entity(
$this->entity,
$this->version,
$this->language
);
}
return null;
}
/** /**
* Return the content for the page. If its an actual documentation page then * Return the content for the page. If its an actual documentation page then
* display the content from the page, otherwise display the contents from * display the content from the page, otherwise display the contents from
@ -303,35 +288,7 @@ class DocumentationViewer extends Controller {
public function getContent() { public function getContent() {
$page = $this->getPage(); $page = $this->getPage();
if($page) { return DBField::create_field("HTMLText", $page->getHTML());
return DBField::create_field("HTMLText", $page->getHTML(
$this->getVersion(), $this->getLanguage()
));
}
// If no page found then we may want to get the listing of the folder.
// In case no folder exists, show a "not found" page.
$entity = $this->getEntity();
$url = $this->Remaining;
if($url && $entity) {
// @todo manifest
return $this->customise(array(
'Content' => false,
'Title' => DocumentationService::clean_page_name(array_pop($url)),
'Pages' => $pages
))->renderWith('DocumentationFolderListing');
}
else {
return $this->customise(array(
'Content' => false,
'Title' => _t('DocumentationViewer.MODULES', 'Modules'),
'Pages' => $this->getEntities()
))->renderWith('DocumentationFolderListing');
}
return false;
} }
/** /**
@ -424,43 +381,6 @@ class DocumentationViewer extends Controller {
return new DocumentationSearchForm($this); return new DocumentationSearchForm($this);
} }
/**
* 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() {
$version = $this->getVersion();
$entity = $this->getEntity();
if($entity) {
$compare = $entity->compare($version);
$stable = $entity->getStableVersion();
// same
if($version == $stable) return false;
// check for trunk, if trunk and not the same then it's future
// also run through compare
if($version == "trunk" || $compare > 0) {
return $this->customise(new ArrayData(array(
'FutureRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable)
)));
}
else {
return $this->customise(new ArrayData(array(
'OutdatedRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable)
)));
}
}
return false;
}
/** /**
* Sets the mapping between a entity name and the link for the end user * Sets the mapping between a entity name and the link for the end user
* to jump into editing the documentation. * to jump into editing the documentation.

26
code/extensions/DocumentationStaticPublisherExtension.php
View File

@ -28,30 +28,10 @@
class DocumentationStaticPublisherExtension extends Extension { class DocumentationStaticPublisherExtension extends Extension {
public function alterExportUrls(&$urls) { public function alterExportUrls(&$urls) {
// fetch all the documentation pages for all the registered modules $manifest = new DocumentationManifest(true);
$modules = DocumentationService::get_registered_entities();
foreach($modules as $module) { foreach($manifest->getPages() as $url => $page) {
foreach($module->getLanguages() as $lang) { $urls[$url] = $url;
foreach($module->getVersions() as $version) {
$pages = DocumentationService::get_pages_from_folder(
$module,
false,
true,
$version,
$lang
);
if($pages) {
foreach($pages as $page) {
$link = $page->getLink(false);
$urls[$link] = $link;
}
}
}
}
} }
} }
} }

42
code/extensions/DocumentationViewerVersionWarning.php Normal file
View File

@ -0,0 +1,42 @@
<?php
/**
* 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
*/
class DocumentationViewerVersionWarning extends Extension {
public function VersionWarning() {
$page = $this->owner->getPage();
$version = $this->owner->getVersion();
$versions = $this->owner->getVersions();
if($page && $verions->count() > 0) {
$stable = $this->owner->getStableVersion();
$compare = $version->compare($stable);
// same
if($version == $stable) {
return false;
}
if($version == "master" || $compare > 0) {
return $this->customise(new ArrayData(array(
'FutureRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable)
)));
}
else {
return $this->customise(new ArrayData(array(
'OutdatedRelease' => true,
'StableVersion' => DBField::create_field('HTMLText', $stable)
)));
}
}
return false;
}
}

2
code/forms/DocumentationAdvancedSearchForm.php
View File

@ -6,7 +6,7 @@
class DocumentationAdvancedSearchForm extends Form { class DocumentationAdvancedSearchForm extends Form {
public function __construct($controller) { public function __construct($controller) {
$entities = DocumentationService::get_registered_entities(); $entities = $controller->getEntities();
$versions = array(); $versions = array();
foreach($entities as $entity) { foreach($entities as $entity) {

46
code/models/DocumentationEntity.php
View File

@ -2,9 +2,16 @@
/** /**
* A {@link DocumentationEntity} represents a module or folder with * A {@link DocumentationEntity} represents a module or folder with
* documentation not an individual page. Entities are loaded via * documentation. An entity not an individual page but a `section` of
* {@link DocumentationService::register()} and individual pages are represented * documentation.
* by a {@link DocumentationPage} and are loaded by the manifest. *
* Each section must have a version (defaults to `master`) which stores the
* actual path to the documentation (i.e framework 3.0, 3.1 docs point to
* different paths).
*
* Under each {@link DocumentationEntityVersion} contains languages. Most people
* will just have the one `en` folder but that translates to the
* {@link DocumentationEntityLanguage} instance to which the page relates to.
* *
* *
* @package docsviewer * @package docsviewer
@ -81,20 +88,6 @@ class DocumentationEntity extends ViewableData {
return array_pop($sortedVersions); return array_pop($sortedVersions);
} }
/**
* 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
* the same and 1 if the version is greater than.
*
* @param string $version
* @return int
*/
public function compare($version) {
$latest = $this->getStableVersion();
return version_compare($version, $latest);
}
/** /**
* Return whether we have a given version of this entity * Return whether we have a given version of this entity
* *
@ -153,7 +146,9 @@ class DocumentationEntity extends ViewableData {
} }
/** /**
* Returns the web accessible link to this Entity * Returns the web accessible link to this entity. This does not include any
* of the language information, the URL without the language should be a
* permanent direct to 'en' documentation or the first language.
* *
* @return string * @return string
*/ */
@ -171,4 +166,19 @@ class DocumentationEntity extends ViewableData {
return sprintf('DocumentationEntity: %s)', $this->getPath()); return sprintf('DocumentationEntity: %s)', $this->getPath());
} }
/**
* @param DocumentationPage $page
*
* @return boolean
*/
public function hasRecord(DocumentationPage $page) {
foreach($this->getVersions() as $version) {
foreach($version->getSupportedLanguages() as $lang) {
if($lang === $page->getEntity()) {
return true;
}
}
}
}
} }

4
code/models/DocumentationEntityLanguage.php
View File

@ -28,7 +28,9 @@ class DocumentationEntityLanguage extends ViewableData {
* @return string * @return string
*/ */
public function Link() { public function Link() {
return Controller::join_links($this->entity->Link(), $this->language); return Controller::join_links(
$this->entity->Link(), $this->language
);
} }

13
code/models/DocumentationEntityVersion.php
View File

@ -127,4 +127,17 @@ class DocumentationEntityVersion extends ViewableData {
public function getTitle() { public function getTitle() {
return $this->entity->getTitle(); return $this->entity->getTitle();
} }
/**
* 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
* the same and 1 if the version is greater than.
*
* @param string $version
* @return int
*/
public function compare(DocumentationEntityVersion $other) {
return version_compare($this->getVersion(), $other->getVersion());
}
} }

6
code/models/DocumentationPage.php
View File

@ -47,7 +47,7 @@ class DocumentationPage extends ViewableData {
* @return string * @return string
*/ */
public function getExtension() { public function getExtension() {
return DocumentationService::get_extension($this->filename); return DocumentationHelper::get_extension($this->filename);
} }
/** /**
@ -61,7 +61,9 @@ class DocumentationPage extends ViewableData {
// add the module to the breadcrumb trail. // add the module to the breadcrumb trail.
array_unshift($pathParts, $this->entity->getTitle()); array_unshift($pathParts, $this->entity->getTitle());
$titleParts = array_map(array('DocumentationHelper', 'clean_page_name'), $pathParts); $titleParts = array_map(array(
'DocumentationHelper', 'clean_page_name'
), $pathParts);
return implode($divider, $titleParts + array($this->getTitle())); return implode($divider, $titleParts + array($this->getTitle()));
} }

117
docs/en/configuration.md
View File

@ -3,46 +3,29 @@
## Registering what to document ## Registering what to document
By default the documentation system will parse all the directories in your By default the documentation system will parse all the directories in your
project and include the documentation. If you want to only specify a few folders project and include the documentation from those modules `docs` directory.
you can disable it and register your paths manually
:::php If you want to only specify a few folders or have documentation in a non
// turns off automatic parsing of filesystem standard location you can disable the autoload behaviour and register your
DocumentationService::set_automatic_registration(false); folders manually through the `Config` API.
// registers module 'sapphire' In YAML this looks like:
try {
DocumentationService::register("sapphire", BASE_PATH ."/sapphire/docs/", 'trunk');
} catch(InvalidArgumentException $e) { `mysite/_config/docsviewer.yml`
} :::yaml
---
name: docsviewer
after: docsviewer#docsviewer
---
DocumentationManifest:
automatic_registration: false
register_entities:
-
Path: "framework/docs/"
Title: "Framework Documentation"
If you only want to disable documentation for one module you can correspondingly
call unregister()
:::php
DocumentationService::unregister($module, $version = false, $lang = false)
Unregister a module. You can specify the module, the version and the lang. If
no version is specified then all folders of that lang are removed. If you do
not specify a version or lang the whole module will be removed from the
documentation.
## Hiding files from listing
If you want to ignore (hide) certain file types from being included in the
listings. By default this is the list of hidden files
:::php
$files = array(
'.', '..', '.DS_Store', '.svn', '.git', 'assets', 'themes', '_images'
);
DocumentationService::set_ignored_files($files);
## Permalinks ## Permalinks
Permalinks can be setup to make nicer urls or to help redirect older urls Permalinks can be setup to make nicer urls or to help redirect older urls
@ -58,72 +41,26 @@ to new structures.
Custom metadata can be added to the head of the MarkDown file like this: Custom metadata can be added to the head of the MarkDown file like this:
pagenumber: 1
title: A custom title title: A custom title
Make sure to add an empty line to separate the metadata from the content of Make sure to add an empty line to separate the metadata from the content of
the file. the file.
**Note:** SilverStripe needs to read the contents of each page to retrieve the The currently utilized metadata tags for the module are
metadata. This is expensive, so if you do not plan to use custom sorting,
do not enable this feature: title: 'A custom title for menus, breadcrumbs'
summary: 'A custom introduction text'
### Custom page sorting ### Custom page sorting
By default pages in the lefthand menu are sorted alphabetically. Adding a By default pages in the left hand menu are sorted as how they appear in the file
pagenumber to the metadata, like in the example above, allows for custom system. You can manually set the order by prefixing filenames with numbers. For
pagenumbering. example:
**Note:** although folders appear in the menu as 'pages', you obviously can't 00_file-first.md
number them, so you need to number their index.php page instead. 01_second-file.md
Pages that have no custom pagenumber, keep their original The leading numbers will be scrubbed from the URL and page link.
order, but for them not to interfere with custom sort, they also receive a
pagenumber, starting at 10.000.
You can change this starting point for default pagenumbers:
```php
DocumentationService:: start_pagenumbers_at(80);
```
### Other key-value pairs
Basically all DocumentationPage properties can be added to the metadata comment
block. Beware that the outcome isn't always predictable. Adding a title
property to the block will change the menu title, but the breadcrumbs
are at this time not yet supported.
The files have to end with the __.md__ or __.markdown__ extension. The
documentation viewer will automatically replace hyphens (-) with spaces.
my-documentation-file.md
Translates to:
My documentation file
The module also support number prefixing for specifying the order of pages in
the index pages and navigation trees.
03-foo.md
1-bar.md
4-baz.md
Will be output as the following in the listing views.
Bar
Foo
Baz
## Localization
All documentation folder should be localized. Even if you do not plan on supporting
multiple languages you need to write your documentation in a 'en' subfolder
/module/docs/en/
## Syntax ## Syntax

3
javascript/DocumentationViewer.js
View File

@ -104,10 +104,11 @@
title.after(toc); title.after(toc);
} else { } else {
var breadcrums = $('#content .doc-breadcrumbs'); var breadcrums = $('#content .doc-breadcrumbs');
if (breadcrums.length > 0) { if (breadcrums.length > 0) {
breadcrums.after(toc); breadcrums.after(toc);
} else { } else {
$('#content').prepend(toc); $('#table-contents-holder').prepend(toc);
} }
} }

2
templates/Layout/DocumentationViewer_DocumentationPage.ss
View File

@ -7,6 +7,8 @@
<% include DocumentationBreadcrumbs %> <% include DocumentationBreadcrumbs %>
<% end_if %> <% end_if %>
<% include DocumentationTableContents %>
$Content $Content
<% include DocumentationNextPrevious %> <% include DocumentationNextPrevious %>

3
tests/DocumentationManifestTests.php
View File

@ -1,7 +1,8 @@
<?php <?php
/** /**
* * @package docsviewer
* @subpackage tests
*/ */
class DocumentationManifestTests extends SapphireTest { class DocumentationManifestTests extends SapphireTest {

20
tests/DocumentationViewerTest.php
View File

@ -232,27 +232,7 @@ class DocumentationViewerTest extends FunctionalTest {
} }
} }
function testVersionWarning() {
$v = new DocumentationViewer();
// the current version is set to 2.4, no notice should be shown on that page
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.4'), DataModel::inst());
$this->assertFalse($v->VersionWarning());
// 2.3 is an older release, hitting that should return us an outdated flag
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.3'), DataModel::inst());
$warn = $v->VersionWarning();
$this->assertTrue($warn->OutdatedRelease);
$this->assertNull($warn->FutureRelease);
// 3.0 is a future release
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/3.0'), DataModel::inst());
$warn = $v->VersionWarning();
$this->assertNull($warn->OutdatedRelease);
$this->assertTrue($warn->FutureRelease);
}
/** /**
* Test that the pages comes back sorted by filename * Test that the pages comes back sorted by filename

60
tests/DocumentationViewerVersionWarningTest.php Normal file
View File

@ -0,0 +1,60 @@
<?php
class DocumentationViewerVersionWarningTest extends SapphireTest {
protected $autoFollowRedirection = false;
public function setUpOnce() {
parent::setUpOnce();
$this->origEnabled = DocumentationService::automatic_registration_enabled();
DocumentationService::set_automatic_registration(false);
$this->origModules = DocumentationService::get_registered_entities();
$this->origLinkBase = Config::inst()->get('DocumentationViewer', 'link_base');
Config::inst()->update('DocumentationViewer', 'link_base', 'dev/docs/');
foreach($this->origModules as $module) {
DocumentationService::unregister($module->getFolder());
}
// We set 3.0 as current, and test most assertions against 2.4 - to avoid 'current' rewriting issues
DocumentationService::register("DocumentationViewerTests", DOCSVIEWER_PATH . "/tests/docs/", '2.3');
DocumentationService::register("DocumentationViewerTests", DOCSVIEWER_PATH . "/tests/docs-v2.4/", '2.4', 'Doc Test', true);
DocumentationService::register("DocumentationViewerTests", DOCSVIEWER_PATH . "/tests/docs-v3.0/", '3.0', 'Doc Test');
DocumentationService::register("DocumentationViewerAltModule1", DOCSVIEWER_PATH . "/tests/docs-parser/", '1.0');
DocumentationService::register("DocumentationViewerAltModule2", DOCSVIEWER_PATH . "/tests/docs-search/", '1.0');
}
public function tearDownOnce() {
parent::tearDownOnce();
DocumentationService::unregister("DocumentationViewerTests");
DocumentationService::set_automatic_registration($this->origEnabled);
Config::inst()->update('DocumentationViewer', 'link_base', $this->origLinkBase);
}
public function testVersionWarning() {
$v = new DocumentationViewer();
// the current version is set to 2.4, no notice should be shown on that page
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.4'), DataModel::inst());
$this->assertFalse($v->VersionWarning());
// 2.3 is an older release, hitting that should return us an outdated flag
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.3'), DataModel::inst());
$warn = $v->VersionWarning();
$this->assertTrue($warn->OutdatedRelease);
$this->assertNull($warn->FutureRelease);
// 3.0 is a future release
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/3.0'), DataModel::inst());
$warn = $v->VersionWarning();
$this->assertNull($warn->OutdatedRelease);
$this->assertTrue($warn->FutureRelease);
}
}