tonyair
/
silverstripe-docsviewer
mirror of https://github.com/silverstripe/silverstripe-docsviewer
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

BUGFIX: fixed bug with linking to internal assets.

This commit is contained in:
Will Rossiter 2011-07-04 16:58:15 +12:00
parent cb19549a97
commit 96ac20a15c
14 changed files with 270 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
code/DocumentationParser.php
View File

@ -270,6 +270,9 @@ class DocumentationParser {
$relativePath = dirname($page->getRelativePath());
if($relativePath == '.') $relativePath = '';
// file base link
$fileBaseLink = Director::makeRelative(dirname($page->getPath()));
if($matches) {
foreach($matches[0] as $i => $match) {
$title = $matches[2][$i];
@ -282,15 +285,25 @@ class DocumentationParser {
$urlParts = parse_url($url);
if($urlParts && isset($urlParts['scheme'])) continue;
// Rewrite URL
if(preg_match('/^\//', $url)) {
// Absolute: Only path to module base
$relativeUrl = Controller::join_links($baselink, $url);
} else {
// Relative: Include path to module base and any folders
$relativeUrl = Controller::join_links($baselink, $relativePath, $url);
// for images we need to use the file base path
if(preg_match('/_images/', $url)) {
$relativeUrl = Controller::join_links(
Director::absoluteBaseURL(),
$fileBaseLink,
$url
);
}
else {
// Rewrite public URL
if(preg_match('/^\//', $url)) {
// Absolute: Only path to module base
$relativeUrl = Controller::join_links($baselink, $url);
} else {
// Relative: Include path to module base and any folders
$relativeUrl = Controller::join_links($baselink, $relativePath, $url);
}
}
// Resolve relative paths
while(strpos($relativeUrl, '..') !== FALSE) {
$relativeUrl = preg_replace('/\w+\/\.\.\//', '', $relativeUrl);

67
code/DocumentationService.php
View File

@ -36,7 +36,7 @@ class DocumentationService {
*
* @var array
*/
public static $valid_markdown_extensions = array('.md', '.txt', '.markdown');
public static $valid_markdown_extensions = array('md', 'txt', 'markdown');
/**
* Registered {@link DocumentationEntity} objects to include in the documentation.
@ -78,6 +78,16 @@ class DocumentationService {
return self::$valid_markdown_extensions;
}
/**
* Check to see if a given extension is a valid extension to be rendered.
* Assumes that $ext has a leading dot as that is what $valid_extension uses.
*
* @return bool
*/
public static function is_valid_extension($ext) {
return in_array(strtolower($ext), self::get_valid_extensions());
}
/**
* Set the ignored files list
*
@ -313,35 +323,27 @@ class DocumentationService {
private static function find_page_recursive($base, $goal) {
$handle = opendir($base);
$name = strtolower(array_shift($goal));
$name = self::trim_extension_off(strtolower(array_shift($goal)));
if(!$name || $name == '/') $name = 'index';
if($handle) {
$extensions = DocumentationService::get_valid_extensions();
if($handle) {
$ignored = self::get_ignored_files();
// ensure we end with a slash
$base = rtrim($base, '/') .'/';
while (false !== ($file = readdir($handle))) {
if(in_array($file, DocumentationService::get_valid_extensions())) continue;
if(in_array($file, $ignored)) continue;
$formatted = strtolower($file);
// if the name has a . then take the substr
$formatted = ($pos = strrpos($formatted, '.')) ? substr($formatted, 0, $pos) : $formatted;
if($dot = strrpos($name, '.')) {
if(in_array(substr($name, $dot), self::get_valid_extensions())) {
$name = substr($name, 0, $dot);
}
}
$formatted = self::trim_extension_off(strtolower($file));
// the folder is the one that we are looking for.
if(strtolower($name) == strtolower($formatted)) {
// if this file is a directory we could be displaying that
// or simply moving towards the goal.
if(is_dir($base . $file)) {
if(is_dir(Controller::join_links($base, $file))) {
$base = $base . trim($file, '/') .'/';
@ -402,30 +404,36 @@ class DocumentationService {
}
/**
* Helper function to strip the extension off.
* Warning: Doesn't work if the filename includes dots,
* but no extension, e.g. "2.4.0-alpha" will return "2.4".
* Helper function to strip the extension off and return the name without
* the extension. If you need the extension see {@link get_extension()}
*
* @param string
*
* @return string
*/
public static function trim_extension_off($name) {
$hasExtension = strrpos($name, '.');
$ext = self::get_extension($name);
if($hasExtension !== false && $hasExtension > 0) {
$shorted = substr($name, $hasExtension);
// can remove the extension only if we know how
// to read it again
if(in_array(rtrim($shorted, '/'), self::get_valid_extensions())) {
$name = substr($name, 0, $hasExtension);
if($ext) {
if(self::is_valid_extension($ext)) {
return substr($name, 0, strrpos($name,'.'));
}
}
return $name;
}
/**
* Returns the extension from a string. If you want to trim the extension
* off the end of the string see {@link trim_extension_off()}
*
* @param string
*
* @return string
*/
public static function get_extension($name) {
return substr(strrchr($name,'.'), 1);
}
/**
* Return the children from a given entity sorted by Title using natural ordering.
@ -499,7 +507,6 @@ class DocumentationService {
$handle = opendir($folder);
if($handle) {
$extensions = self::get_valid_extensions();
$ignore = self::get_ignored_files();
$files = array();
@ -510,11 +517,13 @@ class DocumentationService {
$relativeFilePath = Controller::join_links($relative, $file);
if(is_dir($path)) {
// dir
$pages[] = $relativeFilePath;
if($recusive) self::get_pages_from_folder_recursive($base, $relativeFilePath, $recusive, $pages);
}
else if(in_array(substr($file, (strrpos($file, '.'))), $extensions)) {
else if(self::is_valid_extension(self::get_extension($path))) {
// file we want
$pages[] = $relativeFilePath;
}
}

17
code/controllers/DocumentationViewer.php
View File

@ -141,7 +141,9 @@ class DocumentationViewer extends Controller {
if($firstParam) {
// allow assets
if($firstParam == "assets") return parent::handleRequest($request);
if($firstParam == "assets") {
return parent::handleRequest($request);
}
// check for permalinks
if($link = DocumentationPermalinks::map($firstParam)) {
@ -329,9 +331,6 @@ class DocumentationViewer extends Controller {
* @return DataObject
*/
function getEntities($version = false, $lang = false) {
if(!$version) $version = $this->getVersion();
if(!$lang) $lang = $this->getLang();
$entities = DocumentationService::get_registered_entities($version, $lang);
$output = new DataObjectSet();
@ -342,7 +341,7 @@ class DocumentationViewer extends Controller {
$mode = ($entity === $currentEntity) ? 'current' : 'link';
$folder = $entity->getFolder();
$link = $this->Link(array_slice($this->Remaining, -1, -1), $folder, $version, $lang);
$link = $this->Link(array(), $folder, false, $lang);
$content = false;
if($page = $entity->getIndexPage($version, $lang)) {
@ -602,6 +601,8 @@ class DocumentationViewer extends Controller {
if($pages) {
$path = array();
$version = $this->getVersion();
$lang = $this->getLang();
foreach($pages as $i => $title) {
if($title) {
@ -610,7 +611,7 @@ class DocumentationViewer extends Controller {
$output->push(new ArrayData(array(
'Title' => DocumentationService::clean_page_name($title),
'Link' => rtrim($this->Link($path), "/"). "/"
'Link' => rtrim($this->Link($path, false, $version, $lang), "/"). "/"
)));
}
}
@ -651,7 +652,9 @@ class DocumentationViewer extends Controller {
public function Link($path = false, $entity = false, $version = false, $lang = false) {
$base = Director::absoluteBaseURL();
$version = (!$version) ? $this->getVersion() : $version;
// only include the version. Version is optional after all
$version = ($version === null) ? $this->getVersion() : $version;
$lang = (!$lang) ? $this->getLang() : $lang;
$entity = (!$entity && $this->entity) ? $this->entity : $entity;

21
code/models/DocumentationPage.php
View File

@ -66,6 +66,13 @@ class DocumentationPage extends ViewableData {
$this->relativePath = $path;
}
/**
* @return string
*/
function getExtension() {
return DocumentationService::get_extension($this->getRelativePath());
}
/**
* Absolute path including version and lang folder.
*
@ -209,17 +216,23 @@ class DocumentationPage extends ViewableData {
}
/**
* Return the raw markdown for a given documentation page
* Return the raw markdown for a given documentation page. Will throw
* an error if the path isn't a file.
*
* @throws InvalidArgumentException
* @return String
* Will return empty if the type is not readable
*
* @return string
*/
function getMarkdown() {
try {
$path = $this->getPath(true);
if($path) {
return file_get_contents($path);
$ext = $this->getExtension();
if(DocumentationService::is_valid_extension($ext)) {
return file_get_contents($path);
}
}
}
catch(InvalidArgumentException $e) {}

61
docs/en/Configuration-Options.md
View File

@ -1,33 +1,56 @@
# Helpful Configuration Options
# Configuration Options
DocumentationService::set_ignored_files(array());
## Registering what to document
If you want to ignore (hide) certain file types from being included.
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 you can
disable it and register your paths manually
:::php
// turns off automatic parsing of filesystem
DocumentationService::set_automatic_registration(false);
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 you can disable it
with the above.
DocumentationService::register($module, $path, $version = 'current', $lang = 'en', $major_release = false)
Registers a module to be included in the system (if automatic registration is off or you need
to load a module outside a documentation path).
DocumentationService::unregister($module, $version = false, $lang = false)
// registers module 'sapphire'
try {
DocumentationService::register("sapphire", BASE_PATH ."/sapphire/docs/", 'trunk');
} catch(InvalidArgumentException $e) {
}
Unregister a module (removes from documentation list). 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.
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
You can set short names for longer urls so they are easier to remember. Set the following in your mysite/_config.php file:
Permalinks can be setup to make nicer urls or to help redirect older urls
to new structures.
DocumentationPermalinks::add(array(
'debugging' => 'current/en/sapphire/topics/debugging',
'templates' => 'current/en/sapphire/topics/templates'
'debugging' => 'sapphire/en/topics/debugging',
'templates' => 'sapphire/en/topics/templates'
));

77
docs/en/Writing-Documentation.md
View File

@ -1,32 +1,67 @@
# Writing Documentation #
# 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/.
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 (since you cannot
have spaces web / file systems).
The files have to end with the __.md__ extension. The documentation viewer will
automatically replace hyphens (-) with spaces.
Also docs folder should be localized. Even if you do not plan on using multiple languages you should at least write your documentation
in a 'en' subfolder
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
This uses a customized markdown extra parser. To view the syntax for page formatting check out [Daring Fireball](http://daringfireball.net/projects/markdown/syntax)
Documentation should be written in markdown with an `.md` extension attached.
To view the syntax for page formatting check out [Daring Fireball](http://daringfireball.net/projects/markdown/syntax).
## Creating Hierarchy ##
To see how to use the documentation from examples, I recommend opening up this
file in your text editor and playing around. As these files are plain text, any
text editor will be able to open and write markdown files.
## Creating Hierarchy
The document viewer supports a hierarchical folder structure so you can categorize
documentation and create topics.
## Directory Listing
Each folder you create should also contain a __index.md__ file which contains
an overview of the module and related links. If no index is available, the
default behaviour is to display an ordered list of links.
## Table of Contents
The table of contents on each module page is generated based on where and what
headers you use.
The document viewer supports folder structure. There is a 9 folder limit on depth / number of sub categories you can create.
Each level deep it will generate the nested urls.
## Directory Listing ##
## Images and Files
Each folder you create should also contain a __index.md__ file (see sapphiredocs/doc/en/index.md) which contains an overview of the
module and related links.
## Table of Contents ##
The table of contents on each module page is generated
If you want to attach images and other assets to a page you need to bundle those
in a directory called _images at the same level as your documentation.

49
templates/Includes/DocInThisModule.ss
View File

@ -1,23 +1,26 @@
<div id="sibling-pages" class="sidebar-box">
<ul>
<% control EntityPages %>
<li>
<a href="$Link" class="$LinkingMode">$Title</a>
<% if Children %>
<ul>
<% control Children %>
<li><a href="$Link" class="$LinkingMode">$Title</a>
<% if Children %>
<ul>
<% control Children %>
<li><a href="$Link" class="$LinkingMode">$Title</a></li>
<% end_control %>
</ul><% end_if %>
</li>
<% end_control %>
</ul>
<% end_if %>
</li>
<% end_control %>
</ul>
</div>
<% if EntityPages %>
<div id="sibling-pages" class="sidebar-box">
<h4>In this module:</h4>
<ul>
<% control EntityPages %>
<li>
<a href="$Link" class="$LinkingMode">$Title</a>
<% if Children %>
<ul>
<% control Children %>
<li><a href="$Link" class="$LinkingMode">$Title</a>
<% if Children %>
<ul>
<% control Children %>
<li><a href="$Link" class="$LinkingMode">$Title</a></li>
<% end_control %>
</ul><% end_if %>
</li>
<% end_control %>
</ul>
<% end_if %>
</li>
<% end_control %>
</ul>
</div>
<% end_if %>

20
tests/DocumentationParserTest.php
View File

@ -237,4 +237,24 @@ HTML;
$parsed
);
}
function testRewritingRelativeLinksToFiles() {
$folder = '/sapphiredocs/tests/docs-parser/';
$page = new DocumentationPage();
$page->setRelativePath('file-download.md');
$page->setEntity(new DocumentationEntity('parser', '2.4', BASE_PATH . $folder));
$parsed = DocumentationParser::parse($page, $folder);
$this->assertContains(
Controller::join_links($folder, '/en/_images/external_link.png'),
$parsed
);
$this->assertContains(
Controller::join_links($folder, '/en/_images/test.tar.gz'),
$parsed
);
}
}

15
tests/DocumentationServiceTest.php
View File

@ -11,7 +11,6 @@ class DocumentationServiceTest extends SapphireTest {
$entity = DocumentationService::register('testdocs', BASE_PATH . '/sapphiredocs/tests/docs/');
$pages = DocumentationService::get_pages_from_folder($entity);
// check folders and files exist as their filenames
$this->assertContains('index.md', $pages->column('Filename'), 'The tests/docs/en folder should contain a index file');
$this->assertContains('subfolder/', $pages->column('Filename'), 'The tests/docs/en folder should contain a subfolder called subfolder');
$this->assertContains('test.md', $pages->column('Filename'), 'The tests/docs/en folder should contain a test file');
@ -96,4 +95,18 @@ class DocumentationServiceTest extends SapphireTest {
$this->assertEquals(DocumentationService::clean_page_name($value), $should[$key]);
}
}
function testIsValidExtension() {
$this->assertTrue(DocumentationService::is_valid_extension('md'));
$this->assertTrue(DocumentationService::is_valid_extension('markdown'));
$this->assertTrue(DocumentationService::is_valid_extension('MD'));
$this->assertTrue(DocumentationService::is_valid_extension('MARKDOWN'));
$this->assertFalse(DocumentationService::is_valid_extension('.markd'));
$this->assertFalse(DocumentationService::is_valid_extension('.exe'));
// require an extension as internally we check for extension, not using
// one could cause issues.
$this->assertFalse(DocumentationService::is_valid_extension(''));
}
}

21
tests/DocumentationViewerTest.php
View File

@ -29,6 +29,9 @@ class DocumentationViewerTest extends FunctionalTest {
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("DocumentationViewerAltModule1", BASE_PATH . "/sapphiredocs/tests/docs-parser/", '1.0');
DocumentationService::register("DocumentationViewerAltModule2", BASE_PATH . "/sapphiredocs/tests/docs-search/", '1.0');
}
function tearDownOnce() {
@ -113,7 +116,7 @@ class DocumentationViewerTest extends FunctionalTest {
$this->assertEquals('Subfolder', $page->Title);
}
function testGetModulePages() {
function testGetEntityPages() {
$v = new DocumentationViewer();
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.3/subfolder/'));
$pages = $v->getEntityPages();
@ -231,4 +234,20 @@ class DocumentationViewerTest extends FunctionalTest {
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/3.0'));
$this->assertEquals('3.0', $v->getVersion());
}
function testGetEntities() {
$v = new DocumentationViewer();
$response = $v->handleRequest(new SS_HTTPRequest('GET', 'DocumentationViewerTests/en/2.4'));
$pages = $v->getEntities();
$this->assertEquals(3, $pages->Count(), 'Registered 3 entities');
// check to see the links don't have version or pages in them
foreach($pages as $page) {
$expected = Controller::join_links('docs', $page->Title, 'en');
$this->assertStringEndsWith($expected, $page->Link);
}
}
}

BIN
tests/docs-parser/en/_images/external_link.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 B

BIN
tests/docs-parser/en/_images/test.tar.gz Normal file
View File

Binary file not shown.

6
tests/docs-parser/en/file-download.md Normal file
View File

@ -0,0 +1,6 @@
# File test
[image](_images/external_link.png)
[tar.gz](_images/test.tar.gz)

BIN
tests/docs/en/_images/external_link.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 144 B