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

@@ -38,6 +38,9 @@ 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
 documentation viewer see the detailed [documentation](docs/en/configuration.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

@@ -25,6 +25,10 @@ In YAML this looks like:
 	      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.