From 34e98c68f030d526eab2f3ef7eeddcd0ecd5163b Mon Sep 17 00:00:00 2001 From: David Alexander Date: Fri, 12 Feb 2016 00:19:29 -0700 Subject: [PATCH] Renamed methods and variables for clarity; tidied code typos more typos updated README typos --- README.md | 51 ++++++++++++++----- app/_config/docs-repositiories.yml | 2 +- app/code/DocsCronTask.php | 27 ---------- ...UpdateTask.php => RefreshMarkdownTask.php} | 37 +++++++------- app/code/UpdateDocsCronTask.php | 28 ++++++++++ 5 files changed, 86 insertions(+), 59 deletions(-) delete mode 100644 app/code/DocsCronTask.php rename app/code/{UpdateTask.php => RefreshMarkdownTask.php} (71%) create mode 100644 app/code/UpdateDocsCronTask.php diff --git a/README.md b/README.md index 3097583..77c3811 100644 --- a/README.md +++ b/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. - 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. diff --git a/app/_config/docs-repositiories.yml b/app/_config/docs-repositiories.yml index 78f050d..b6bbacf 100644 --- a/app/_config/docs-repositiories.yml +++ b/app/_config/docs-repositiories.yml @@ -4,7 +4,7 @@ After: - framework/* - cms/* --- -UpdateTask: +RefreshMarkdownTask: documentation_repositories: - - silverstripe/silverstripe-framework diff --git a/app/code/DocsCronTask.php b/app/code/DocsCronTask.php deleted file mode 100644 index 7e5c3b6..0000000 --- a/app/code/DocsCronTask.php +++ /dev/null @@ -1,27 +0,0 @@ -run(null); - - //reindex the search - $searchtask = new RebuildLuceneDocsIndex(); - $searchtask->run(null); - - } -} \ No newline at end of file diff --git a/app/code/UpdateTask.php b/app/code/RefreshMarkdownTask.php similarity index 71% rename from app/code/UpdateTask.php rename to app/code/RefreshMarkdownTask.php index 503d8a1..bf18556 100644 --- a/app/code/UpdateTask.php +++ b/app/code/RefreshMarkdownTask.php @@ -1,16 +1,22 @@ 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("rm -rf {$path}/src/{$folder}_{$branch}"); - } + exec("mkdir -p {$path}/src"); + 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) { - if ($file !== "docs" && $file !== "." && $file !== "..") { - exec("rm -rf {$file}"); + foreach ($paths as $path) { + if ($path !== "docs" && $path !== "." && $path !== "..") { + exec("rm -rf {$path}"); } } } -} \ No newline at end of file +} diff --git a/app/code/UpdateDocsCronTask.php b/app/code/UpdateDocsCronTask.php new file mode 100644 index 0000000..9ada0d7 --- /dev/null +++ b/app/code/UpdateDocsCronTask.php @@ -0,0 +1,28 @@ +run(null); + + //reindex markdown files + $reindex_task = new RebuildLuceneDocsIndex(); + $reindex_task->run(null); + + } +}