Merge pull request #111 from tractorcow/pulls/make-missingdir-warning

ENHANCEMENT A missing sources dir will simply disable that repo with a warning

README.md

@@ -4,7 +4,7 @@
 
 ## Maintainer Contact
 
-* Will Rossiter (Nickname: willr, wrossiter) 
+* Will Rossiter (Nickname: willr, wrossiter)
  <will@fullscreen.io>
 
 ## Requirements
@@ -16,14 +16,14 @@ These are pulled in via Composer.
 
 ## Summary
 
-Reads markdown files from a given list of folders from your installation and 
+Reads markdown files from a given list of folders from your installation and
-provides a web interface for viewing the documentation. Ideal for providing 
+provides a web interface for viewing the documentation. Ideal for providing
-documentation alongside your module or project code. 
+documentation alongside your module or project code.
 
 A variation of this module powers the main SilverStripe developer documentation
 and the user help websites.
 
-For more documentation on how to use the module please read /docs/Writing-Documentation.md 
+For more documentation on how to use the module please read /docs/Writing-Documentation.md
 (or via this in /dev/docs/docsviewer/Writing-Documentation in your webbrowser)
 
 ## Installation
@@ -38,11 +38,14 @@ After installing the files via composer, rebuild the SilverStripe database..
 
 Then start by viewing the documentation at `yoursite.com/dev/docs`.
 
+If something isn't working, you can run the dev task at `yoursite.com/dev/tasks/CheckDocsSourcesTask`
+to automatically check for configuration or source file errors.
+
 Out of the box the module will display the documentation files that have been
-bundled into any of your installed modules. To configure what is shown in the 
+bundled into any of your installed modules. To configure what is shown in the
 documentation viewer see the detailed [documentation](docs/en/configuration.md).
 
-For more information about how to use the module see each of the documentation 
+For more information about how to use the module see each of the documentation
 
 	* [Configuration](docs/en/configuration.md)
 	* [Markdown Syntax](docs/en/markdown.md)

code/DocumentationManifest.php

@@ -132,7 +132,8 @@ class DocumentationManifest
             $key = (isset($details['Key'])) ? $details['Key'] : $details['Title'];
 
             if (!$path || !is_dir($path)) {
-                throw new Exception($details['Path'] . ' is not a valid documentation directory');
+                trigger_error($details['Path'] . ' is not a valid documentation directory', E_USER_WARNING);
+                continue;
             }
 
             $version = (isset($details['Version'])) ? $details['Version'] : '';

code/tasks/CheckDocsSourcesTask.php

@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * Check status of sources dirs
+ */
+class CheckDocsSourcesTask extends BuildTask {
+
+    protected $errors = 0;
+
+    protected $description = "Check validity of all docs source files registered";
+
+    public function start() {
+        if(!Director::is_cli()) {
+            echo "<ul>";
+        }
+    }
+
+    public function end() {
+        if(Director::is_cli()) {
+            echo "\nTotal errors: {$this->errors}\n";
+        } else {
+            echo "</ul>";
+            echo "<p>Total errors: {$this->errors}</p>";
+        }
+    }
+
+    public function showError($error) {
+        $this->errors++;
+        if(Director::is_cli()) {
+            echo "\n$error";
+        } else {
+            echo "<li>" . Convert::raw2xml($error) . "</li>";
+        }
+    }
+
+    /**
+     * Validate all source files
+     *
+     * @param SS_HTTPRequest $request
+     * @throws Exception
+     */
+    public function run($request)
+    {
+        $this->start();
+        $registered = Config::inst()->get('DocumentationManifest', 'register_entities');
+        foreach ($registered as $details) {
+            // validate the details provided through the YAML configuration
+            $required = array('Path', 'Title');
+
+            // Check required configs
+            foreach ($required as $require) {
+                if (!isset($details[$require])) {
+                    $this->showError("$require is a required key in DocumentationManifest.register_entities");
+                }
+            }
+
+            // Check path is loaded
+            $path = $this->getRealPath($details['Path']);
+            if (!$path || !is_dir($path)) {
+                $this->showError($details['Path'] . ' is not a valid documentation directory');
+            }
+        }
+        $this->end();
+    }
+
+    public function getRealPath($path)
+    {
+        if (!Director::is_absolute($path)) {
+            $path = Controller::join_links(BASE_PATH, $path);
+        }
+
+        return $path;
+    }
+}

composer.json

@@ -9,10 +9,10 @@
 		"homepage": "http://wilr.github.io",
 		"email": "will@fullscreen.io"
 	}],
-	"support": [{
+	"support": {
 		"email": "will@fullscreen.io",
 		"irc": "irc://irc.freenode.org/silverstripe"
-	}],
+	},
 	"require": {
 		"silverstripe/framework": "~3.1",
 		"erusev/parsedown-extra": "0.2.2",

docs/en/configuration.md

@@ -1,12 +1,12 @@
 # Configuration Options
 
 ## Registering what to document
-	
-By default the documentation system will parse all the directories in your 
-project and include the documentation from those modules `docs` directory. 
 
-If you want to only specify a few folders or have documentation in a non 
+By default the documentation system will parse all the directories in your
-standard location you can disable the autoload behaviour and register your 
+project and include the documentation from those modules `docs` directory.
+
+If you want to only specify a few folders or have documentation in a non
+standard location you can disable the autoload behaviour and register your
 folders manually through the `Config` API.
 
 In YAML this looks like:
@@ -21,10 +21,14 @@ In YAML this looks like:
 	DocumentationManifest:
 	  automatic_registration: false
 	  register_entities:
-	    - 
+	    -
 	      Path: "framework/docs/"
 	      Title: "Framework Documentation"
 
+
+If something isn't working, you can run the dev task at `yoursite.com/dev/tasks/CheckDocsSourcesTask`
+to automatically check for configuration or source file errors.
+
 ###Branch aliases for the edit link (optional)
 When using entities with multiple versions, one of the branches of documentation may be a development version. For example the 'master' branch. You may have an internally assigned version number for this registered in your .yml configuration.
 
@@ -35,13 +39,13 @@ Example:
 	:::yml
 	DocumentationManifest:
 	  register_entities:
-	    - 
+	    -
 	      Path: "framework/docs/"
 	      Title: "Framework Documentation"
 	      Version: "1.0"
 	      Branch: "master"
 
-## Permalinks 
+## Permalinks
 
 Permalinks can be setup to make nicer urls or to help redirect older urls
 to new structures.
@@ -50,16 +54,16 @@ to new structures.
 		'debugging' => 'sapphire/en/topics/debugging',
 		'templates' => 'sapphire/en/topics/templates'
 	));
-	
+
-	
+
 ## Custom metadata and pagesorting
 
-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:
 
 	title: A custom title
 
 Make sure to add an empty line to separate the metadata from the content of
-the file. 
+the file.
 
 The currently utilized metadata tags for the module are
 
@@ -71,37 +75,37 @@ The currently utilized metadata tags for the module are
 By default pages in the left hand menu are sorted as how they appear in the file
 system. You can manually set the order by prefixing filenames with numbers. For
 example:
-	
+
 	00_file-first.md
 	01_second-file.md
 
 The leading numbers will be scrubbed from the URL and page link.
-	
+
 
 ## 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).
 
-To see how to use the documentation from examples, I recommend opening up this 
+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 
+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 
+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 
+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 
+The table of contents on each module page is generated based on where and what
 headers you use.
 
 ## Images and Files