Merge pull request #109 from SpiritLevel/feature/platform

Renamed methods and variables for clarity; tidied code

README.md

@@ -3,7 +3,7 @@
 This is the source code powering http://docs.silverstripe.org. It
 primarily consists of the SilverStripe
 [framework](https://github.com/silverstripe/silverstripe-framework)
-and [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer)
+and the [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer)
 module with minimal configuration.
 
 For adding functionality or editing the style of the documentation see the 
@@ -15,9 +15,15 @@ To set up a test instance:
 
  * Clone this repository to a LAMP server.
  * Install [Composer](http://docs.silverstripe.org/en/getting_started/composer)
+ * Install [sake](https://docs.silverstripe.org/en/developer_guides/cli/).
  * After installing composer run `composer install --prefer-source` to grab the modules.
- * Run `make update` to check out the repositories from which it builds the
+ * Run the docs crontask in the browser `dev/tasks/UpdateDocsCronTask`
- docs (this will take a while the first time)
+   to download all fresh markdown documentation files and reindex them. Note: this
+   will take some time to run. Alternatively, you can use sake
+   to perform these tasks by firstly running the command `sake
+   dev/tasks/RefreshMarkdownTask flush=1` and secondly `sake
+   dev/tasks/RebuildLuceneDocsIndex flush=1`.
+ * Make sure to flush the cache for markdown content to show up.
 
 ## Source Documentation Files
 
@@ -27,17 +33,33 @@ ignored from this repository to allow for easier updating and to keep this
 project small.
 
 To update or download the source documentation at any time run the following
-make command in your terminal:
+BuildTask command with sake:
 
 	cd /Sites/doc.silverstripe.org/
-	make fetch
+	sake dev/tasks/RefreshMarkdownTask flush=1
 
-`make fetch` will call bin/update.sh to download / update each module as listed
+This build task will download / update each module as listed in the
-in the bin/update.sh file.
+`app/_config/docs-repositories.yml` file. Running `sake
+dev/tasks/RebuildLuceneDocsIndex flush=1` will then create a search
+index and reindex the documentation to facilitate searching.
 
-Once the `make fetch` command has executed and downloaded the latest files,
+Once the build task has executed and downloaded the latest files,
 those files are registered along with the module version the folder relates to
-through the [docsviewer.yml](https://github.com/silverstripe/doc.silverstripe.org/blob/master/app/_config/docsviewer.yml) file.
+through the `app/_config/docsviewer.yml` file.
+
+```yaml
+DocumentationManifest:
+  register_entities:
+    -
+      Path: "src/framework_3.2/docs/"
+      Title: "Developer Documentation"
+      Version: "3.2"
+      Stable: true
+      DefaultEntity: true
+```
+
+Set `Stable: true` on the set of documentation relating the current stable version of SilverStripe.
+
 
 ## Contribution
 
@@ -56,9 +78,12 @@ docs.silverstripe.org via a cron job.
 
 ## Cron job
 
-The cron job keeps docs.silverstripe.org up to date with the latest code. This
+The cron job `UpdateDocsCronTask` includes tasks that fetch the latest documentation for each module from git and rebuilds the search indexes.
-cron task calls `make update`, a script that fetches the latest documentation
-for each module from git and rebuilds the search indexes.
 
-	05 * * * * sites make -f /sites/ss2doc-v2/www/Makefile -C /sites/ss2doc-v2/www update
+	public function getSchedule() {
+        return "0 20 * * *"; // runs process() function every day at 8PM
+	}
 
+## Deployment
+
+Deployment is via the SilverStripe Platform deployment tool and uses StackShare.

app/_config/docs-repositiories.yml

@@ -4,7 +4,7 @@ After:
   - framework/*
   - cms/*
 ---
-UpdateTask:
+RefreshMarkdownTask:
   documentation_repositories:
     -
       - silverstripe/silverstripe-framework

app/code/DocsCronTask.php

@@ -1,27 +0,0 @@
-<?php
-
-class DocsCronTask implements CronTask {
-	/**
-	 * 
-	 * @return string
-	 */
-	public function getSchedule() {
-		return "0 20 * * *";
-	}
-
-	/**
-	 * 
-	 * @return BuildTask
-	 */
-	public function process() {
-
-		//rebuild the docs
-		$docstask = new UpdateTask();
-		$docstask->run(null);
-
-		//reindex the search
-		$searchtask = new RebuildLuceneDocsIndex();
-		$searchtask->run(null);
-
-	}
-}

app/code/RefreshMarkdownTask.php

@@ -1,16 +1,22 @@
 <?php
 
-class UpdateTask extends BuildTask
+class RefreshMarkdownTask extends BuildTask
 {
     /**
-     * @var string
+     * @var array
+     * @config documentation_repositories
      */
-    protected $title = "Updates source markdown files";
+    private static $documentation_repositories;
 
     /**
      * @var string
      */
-    protected $description = "Downloads and cleans source markdown documentation files";
+    protected $title = "Refresh markdown files";
+
+    /**
+     * @var string
+     */
+    protected $description = "Downloads a fresh version of markdown documentation files from source";
 
     /**
      * @var bool
@@ -24,7 +30,7 @@ class UpdateTask extends BuildTask
      */
     public function run($request)
     {
-        $this->printLine("updating...");
+        $this->printLine("refreshing markdown files...");
 
         $repositories = $this->getRepositories();
 
@@ -66,7 +72,7 @@ class UpdateTask extends BuildTask
         {
             return $repos;
         } else {
-            user_error("You need to set 'UpdateTask:documentation_repositories' array in your yaml configuration", E_USER_WARNING);
+            user_error("You need to set 'RefreshMarkdownTask:documentation_repositories' array in a yaml configuration file", E_USER_WARNING);
             return null;
         }
     }
@@ -82,13 +88,8 @@ class UpdateTask extends BuildTask
 
         $path = $this->getPath();
 
-        if (!file_exists("{$path}/src")) {
+        exec("mkdir -p {$path}/src");
-            mkdir("{$path}/src");
+        exec("rm -rf {$path}/src/{$folder}_{$branch}");
-        }
-
-        if (file_exists("{$path}/src/{$folder}_{$branch}")) {
-            exec("rm -rf {$path}/src/{$folder}_{$branch}");
-        }
 
         $this->printLine("cloning " . $remote . "/" . $branch);
 
@@ -107,12 +108,12 @@ class UpdateTask extends BuildTask
      */
     private function cleanRepository(array $repository)
     {
-        $files = array_merge(glob("*"), glob(".*"));
+        $paths = array_merge(glob("*"), glob(".*"));
 
-        foreach ($files as $file) {
+        foreach ($paths as $path) {
-            if ($file !== "docs" && $file !== "." && $file !== "..") {
+            if ($path !== "docs" && $path !== "." && $path !== "..") {
-                exec("rm -rf {$file}");
+                exec("rm -rf {$path}");
             }
         }
     }
-}
+}

app/code/UpdateDocsCronTask.php

@@ -0,0 +1,28 @@
+<?php
+
+class UpdateDocsCronTask implements CronTask 
+{
+    /**
+     * @return string
+     */
+    public function getSchedule() 
+    {
+	return "0 20 * * *";
+    }
+    
+    /**
+     * @return BuildTask
+     */
+    public function process() 
+    {
+	
+        //refresh markdown files
+        $refresh_task = new RefreshMarkdownTask();
+        $refresh_task->run(null);
+	
+        //reindex markdown files
+        $reindex_task = new RebuildLuceneDocsIndex();
+        $reindex_task->run(null);
+	
+    }
+}