Merge pull request #109 from SpiritLevel/feature/platform

Renamed methods and variables for clarity; tidied code
This commit is contained in:
Cam Findlay 2016-02-15 11:20:30 +13:00
commit afecf1891c
5 changed files with 86 additions and 59 deletions

View File

@ -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.
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.

View File

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

View File

@ -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);
}
}

View File

@ -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")) {
mkdir("{$path}/src");
}
if (file_exists("{$path}/src/{$folder}_{$branch}")) {
exec("mkdir -p {$path}/src");
exec("rm -rf {$path}/src/{$folder}_{$branch}");
}
$this->printLine("cloning " . $remote . "/" . $branch);
@ -107,11 +108,11 @@ class UpdateTask extends BuildTask
*/
private function cleanRepository(array $repository)
{
$files = array_merge(glob("*"), glob(".*"));
$paths = array_merge(glob("*"), glob(".*"));
foreach ($files as $file) {
if ($file !== "docs" && $file !== "." && $file !== "..") {
exec("rm -rf {$file}");
foreach ($paths as $path) {
if ($path !== "docs" && $path !== "." && $path !== "..") {
exec("rm -rf {$path}");
}
}
}

View File

@ -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);
}
}