Merge pull request #107 from silverstripe/feature/platform

Making the docs site ready for SilverStripe Platform

.gitignore

@@ -9,3 +9,5 @@
 /staticpublisher/
 /toolbar/
 /display_logic/
+/silverstripe-dynamodb/
+/crontask/

.htaccess

@@ -9,6 +9,23 @@
 	Deny from all
 </Files>
 
+# This denies access to all yml files, since developers might include sensitive
+# information in them. See the docs for work-arounds to serve some yaml files
+<Files *.yml>
+	Order allow,deny
+	Deny from all
+</Files>
+
+ErrorDocument 404 /assets/error-404.html
+ErrorDocument 500 /assets/error-500.html
+
+<IfModule mod_alias.c>
+	RedirectMatch 403 /silverstripe-cache(/|$)
+	RedirectMatch 403 /vendor(/|$)
+	RedirectMatch 403 /composer\.(json|lock)
+	RedirectMatch 403 /assets/\.lucene-index(/|$)
+</IfModule>
+
 <IfModule mod_rewrite.c>
 	RewriteEngine On
 

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
- docs (this will take a while the first time)
+ * Run the docs crontask in the browser `dev/tasks/UpdateDocsCronTask`
+   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
-in the bin/update.sh file.
+This build task will download / update each module as listed in the
+`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
-cron task calls `make update`, a script that fetches the latest documentation
-for each module from git and rebuilds the search indexes.
+The cron job `UpdateDocsCronTask` includes tasks that fetch the latest documentation for each module from git and rebuilds the search indexes.
+
+	public function getSchedule() {
+        return "0 20 * * *"; // runs process() function every day at 8PM
+	}
 
-	05 * * * * sites make -f /sites/ss2doc-v2/www/Makefile -C /sites/ss2doc-v2/www update
+## Deployment
 
+Deployment is via the SilverStripe Platform deployment tool and uses StackShare.

app/_config.php

@@ -4,10 +4,11 @@
 $project = 'app';
 
 global $database;
-$database = 'SS_ssdoc';
 
-if (defined('SS_DATABASE_NAME')) {
+if(defined('SS_DATABASE_NAME') && SS_DATABASE_NAME) {
 	$database = SS_DATABASE_NAME;
+} else {
+	$database = 'SS_ssdoc';
 }
 
 if(isset($_ENV['CLEARDB_DATABASE_URL'])) {
@@ -57,9 +58,7 @@
 ));
 
 // Set shared index (avoid issues with different temp paths between CLI and web users)
-if(file_exists(BASE_PATH . '/.lucene-index')) {
-	Config::inst()->update('DocumentationSearch', 'index_location', BASE_PATH . '/.lucene-index');
-}
+Config::inst()->update('DocumentationSearch', 'index_location', BASE_PATH . '/assets/.lucene-index');
 
 // Fix invalid character in iconv
 // see http://stackoverflow.com/questions/4723135/invalid-characters-for-lucene-text-search

app/_config/config.yml

@@ -9,4 +9,4 @@ StaticExporter:
   disable_sitetree_export: true
 Controller:
   extensions:
-    - ControllerExtension
+    - ControllerExtension

app/_config/docs-repositiories.yml

@@ -0,0 +1,32 @@
+---
+Name: docs-repos
+After:
+  - framework/*
+  - cms/*
+---
+RefreshMarkdownTask:
+  documentation_repositories:
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - master
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - "3.3"
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - "3.2"
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - "3.1"
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - "3.0"
+    -
+      - silverstripe/silverstripe-framework
+      - framework
+      - "2.4"

app/_config/docsviewer.yml

@@ -10,41 +10,35 @@ DocumentationManifest:
   automatic_registration: false
   register_entities:
     -
-      Path: "src/framework_master/docs/"
+      Path: "assets/src/framework_master/docs/"
       Title: "Framework"
       Version: "4.0"
       Branch: "master"
       DefaultEntity: true
     -
-      Path: "src/framework_3/docs/"
-      Title: "Framework"
-      Version: "3.4"
-      Branch: "3"
-      DefaultEntity: true
-    -
-      Path: "src/framework_3.3/docs/"
+      Path: "assets/src/framework_3.3/docs/"
       Title: "Framework"
       Version: "3.3"
       Branch: "3.3"
       DefaultEntity: true
     -
-      Path: "src/framework_3.2/docs/"
+      Path: "assets/src/framework_3.2/docs/"
       Title: "Framework"
       Version: "3.2"
       Stable: true
       DefaultEntity: true
     -
-      Path: "src/framework_3.1/docs/"
+      Path: "assets/src/framework_3.1/docs/"
       Title: "Framework"
       Version: "3.1"
       DefaultEntity: true
     -
-      Path: "src/framework_3.0/docs/"
+      Path: "assets/src/framework_3.0/docs/"
       Title: "Framework"
       Version: "3.0"
       DefaultEntity: true
     -
-      Path: "src/framework_2.4/docs/"
+      Path: "assets/src/framework_2.4/docs/"
       Title: "Framework"
       Version: "2.4"
       DefaultEntity: true

app/_config/routes.yml

@@ -1,5 +1,5 @@
 ---
-Name: docs
+Name: docs-routes
 After: framework/routes#coreroutes
 ---
 Director:

app/_config/toolbar.yml

@@ -22,7 +22,7 @@ Only:
   environment: test
 ---
 GlobalNav:
-  hostname: '//sssites-ssorg-uat.sites.silverstripe.com/'
+  hostname: '//www.silverstripe.org/'
   css_path: '/themes/ssv3/css/toolbar.min.css'
   snippet_path: '/assets'
   use_localhost: false

app/code/RefreshMarkdownTask.php

@@ -0,0 +1,119 @@
+<?php
+
+class RefreshMarkdownTask extends BuildTask
+{
+    /**
+     * @var array
+     * @config documentation_repositories
+     */
+    private static $documentation_repositories;
+
+    /**
+     * @var string
+     */
+    protected $title = "Refresh markdown files";
+
+    /**
+     * @var string
+     */
+    protected $description = "Downloads a fresh version of markdown documentation files from source";
+
+    /**
+     * @var bool
+     */
+    protected $enabled = true;
+
+    /**
+     * @var SS_HTTPRequest $request
+     *
+     * @todo test the initial unlink works with cloned modules
+     */
+    public function run($request)
+    {
+        $this->printLine("refreshing markdown files...");
+
+        $repositories = $this->getRepositories();
+
+        foreach ($repositories as $repository) {
+            $this->cloneRepository($repository);
+            $this->cleanRepository($repository);
+        }
+    }
+
+    /**
+     * @return string
+     *
+     * @todo document this new configuration parameter
+     */
+    private function getPath()
+    {
+        return ASSETS_PATH;
+    }
+
+    /**
+     * @param string $message
+     */
+    private function printLine($message)
+    {
+        $this->eol = Director::is_cli() ? PHP_EOL : "<br>";
+        print $message . $this->eol;
+        flush();
+    }
+
+    /**
+     * Returns the array of repos to source markdown docs from
+     *
+     * @return array
+     *
+     */
+    private function getRepositories()
+    {
+        if($repos = $this->config()->documentation_repositories)
+        {
+            return $repos;
+        } else {
+            user_error("You need to set 'RefreshMarkdownTask:documentation_repositories' array in a yaml configuration file", E_USER_WARNING);
+            return null;
+        }
+    }
+
+    /**
+     * @param array $repository
+     *
+     * @todo test this works with all modules
+     */
+    private function cloneRepository(array $repository)
+    {
+        list($remote, $folder, $branch) = $repository;
+
+        $path = $this->getPath();
+
+        exec("mkdir -p {$path}/src");
+        exec("rm -rf {$path}/src/{$folder}_{$branch}");
+
+        $this->printLine("cloning " . $remote . "/" . $branch);
+
+        chdir("{$path}/src");
+        exec("git clone -q git://github.com/{$remote}.git {$folder}_{$branch} --quiet");
+
+        chdir("{$path}/src/{$folder}_{$branch}");
+        exec("git fetch origin");
+        exec("git checkout -q origin/{$branch}");
+    }
+
+    /**
+     * Clears out any non markdown files stored in assets
+     *
+     * @param array $repository
+     */
+    private function cleanRepository(array $repository)
+    {
+        $paths = array_merge(glob("*"), glob(".*"));
+
+        foreach ($paths as $path) {
+            if ($path !== "docs" && $path !== "." && $path !== "..") {
+                exec("rm -rf {$path}");
+            }
+        }
+    }
+}