tonyair/doc.silverstripe.org
1
0
Fork 0
mirror of https://github.com/silverstripe/doc.silverstripe.org synced 2024-10-22 15:05:50 +00:00
Code Issues Projects Releases Wiki Activity

Merge pull request #131 from SpiritLevel/master

Browse Source 
switched to svn export command for copying documentation files
This commit is contained in:
Cam Findlay 2016-04-22 13:51:33 +12:00
commit d92ce25c5c
2 changed files with 70 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@ -1,58 +1,80 @@
# doc.silverstripe.org
This repository contains the source code powering SilverStripe's developer documentation website https://docs.silverstripe.org.
This repository contains the source code powering [SilverStripe's
developer documentation website](https://docs.silverstripe.org).
The source code here consists primarily of the SilverStripe
The source code here primarily consists of the SilverStripe
[framework](https://github.com/silverstripe/silverstripe-framework)
and the [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer)
module with minimal configuration.
modules with minimal configuration.
**This repository does not contain the most current documentation files**.
**This repository does NOT contain the most current documentation.**
The most current documentation files are not stored here but instead are
stored in each framework repository within a `docs` folder. For
example, the documentation for the master branch of the SilverStripe
framework is stored in
The documentation files are written in the
[markdown](https://docs.silverstripe.org/en/2.4/misc/ss-markdown/)
format and the most current versions of these files and are not stored
here. Instead, they are stored in a `docs` folder alongside the
framework source code in each framework repository. For example, the
documentation markdown files for the master branch of the SilverStripe framework are
stored in
[https://github.com/silverstripe/silverstripe-framework/tree/master/docs](https://github.com/silverstripe/silverstripe-framework/tree/master/docs).
As described below in the Installation section, one must first obtain
and re-index fresh versions of the documentation files from the framework
repositories before being able to view the latest content.
As described below in the **Installation** section, one must first
download the latest versions of the documentation markdown files from
the framework repositories and re-index them before being able to view
the most current content.
For adding functionality or editing the style of the documentation, see the
[docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module.
## Installation
To set up a local instance of `doc.silverstripe.org`:
To set up a local instance of [doc.silverstripe.org](https://github.com/SpiritLevel/doc.silverstripe.org):
* Install [Composer](https://docs.silverstripe.org/en/getting_started/composer).
* Install [sake](https://docs.silverstripe.org/en/developer_guides/cli).
* Clone this repository to a LAMP server. For example, the command
* Clone this repository to a LAMP server. For example, the shell command
```
git clone https://github.com/silverstripe/doc.silverstripe.org path/to/webroot/ssdocs
git clone https://github.com/silverstripe/doc.silverstripe.org path/to/ssdocs
```
will clone this repository into `path/to/webroot/ssdocs`.
* From within `path/to/webroot/ssdocs`, run the command
will clone this repository into `path/to/ssdocs`.
* From within `path/to/ssdocs`, run the command
```
composer install --prefer-source
```
to grab the modules, in particular, the [docsviewer](http://github.com/silverstripe/silverstripe-docsviewer) module.
* From within `path/to/webroot/ssdocs`, run the command
to install all required modules, in particular, the [docsviewer](http://github.com/silverstripe/silverstripe-docsviewer) module.
* If you are only interested in being able to view the documentation locally then, from within `path/to/ssdocs`, run the command
```
sake dev/tasks/RefreshMarkdownTask flush=1
```
to get the latest documentation source markdown files. If you are interested in contributing, instead use the command
to get the latest documentation markdown files.
If you are interested in contributing, you must first install [subversion](https://subversion.apache.org/). For example,
in [Ubuntu](http://www.ubuntu.com/) or [Debian](https://www.debian.org/), `sudo apt-get install subversion` will install subversion. Then run the command
```
sake dev/tasks/RefreshMarkdownTask flush=1 dev=1
```
to get the full git repositories.
* From within `path/to/webroot/ssdocs`, run the command
* From within `path/to/ssdocs`, run the command
```
sake dev/tasks/RebuildLuceneDocsIndex flush=1
```
to re-index the latest documentation source markdown files. Note: re-indexing will take some time.
to re-index the latest documentation markdown files. Note: re-indexing will take some time.
* Make sure to flush the cache for markdown content to show up.
Rather than using [sake](https://docs.silverstripe.org/en/developer_guides/cli), one can instead run the two tasks directly in the
browser. To get the documentation markdown files, use the url:
```
http://localhost/path/to/ssdocs/dev/tasks/RefreshMarkdownTask?flush=1
```
To get the full git repositories use the url
```
http://localhost/path/to/ssdocs/dev/tasks/RefreshMarkdownTask?flush=1&dev=1
```
To re-index the documentation files use the url:
```
http://localhost/path/to/ssdocs/dev/tasks/RebuildLuceneDocsIndex?flush=1
```
## Automation
Refreshing and re-indexing the documentation markdown files can be automated. From within `path/to/webroot/ssdocs`, run the command:
@ -60,8 +82,8 @@ Refreshing and re-indexing the documentation markdown files can be automated. Fr
sake dev/tasks/UpdateDocsCronTask
```
The cron job `UpdateDocsCronTask` runs the `RefreshMarkdownTask`
and `RebuildLuceneDocsIndex` tasks every day at 8PM. This can be
altered by editing `UpdateDocsCronTask.php` and changing the scheduling
and `RebuildLuceneDocsIndex` tasks every day at 8PM. This execution schedule can be
altered by editing `UpdateDocsCronTask.php`, found in the `apps/code` folder, and changing the scheduling
function:
```
public function getSchedule() {
@ -69,22 +91,30 @@ function:
}
```
Rather than using `sake`, one can instead run the cron task directly in the browser using the url:
```
http://localhost/path/to/ssdocs/dev/cron/UpdateDocsCronTask?flush=1
```
## Contribution
To contribute an improvement to the https://docs.silverstripe.org functionality or
theme, submit a pull request on GitHub. Any approved pull requests will make
theme, submit a pull request on the [GitHub project](https://github.com/silverstripe/doc.silverstripe.org). Any approved pull requests will make
their way onto the https://docs.silverstripe.org site in the next release.
If you wish to edit the documentation content, submit a pull request on that
Github project. Updated documentation content is regularly uploaded to https://docs.silverstripe.org via a cron job.
If you wish to edit the documentation content, submit a pull request
on the
[framework Github project](https://github.com/silverstripe/silverstripe-framework). Updated
documentation content is uploaded daily at 8PM to [doc.silverstripe.org](https://docs.silverstripe.org) via a cron job. See the **Automation** section.
If you are adding a new version of the documentation, you must
register it in both `app/_config/docs-repositories.yml` and
`app/_config/docsviewer.yml`. To set one particular version to be the
`app/_config/docsviewer.yml`. To set one particular version to be
current stable version, set `Stable: true` in
`app/_config/docsviewer.yml`. Remove the `Stable: true` setting for
all versions that are not stable.
`app/_config/docsviewer.yml`. Remove the `Stable: true` for all
versions that are not stable.
## Deployment
Deployment is via the SilverStripe Platform deployment tool and uses StackShare.
Deployment is via the [SilverStripe Platform](https://www.silverstripe.com/platform/) deployment tool and uses [StackShare](http://www.silverstripe.com/platform/technical/).

25
app/code/RefreshMarkdownTask.php
View File

@ -36,11 +36,14 @@ class RefreshMarkdownTask extends BuildTask
public function run($request)
{
$this->request = $request;
$this->printLine("Refreshing markdown files...");
$repositories = $this->getRepositories();
foreach ($repositories as $repository) {
$this->cloneRepository($repository);
}
$this->printLine(" ");
$this->printLine("To re-index the freshly downloaded documentation files either:");
$this->printLine("(1) run the command 'sake dev/tasks/RebuildLuceneDocsIndex flush=1' in a shell or");
$this->printLine("(2) point your browser at the url 'http://localhost/path/to/ssdocs/dev/tasks/RebuildLuceneDocsIndex?flush=1'");
}
/**
@ -92,28 +95,20 @@ class RefreshMarkdownTask extends BuildTask
$path = $this->getPath();
exec("mkdir -p {$path}/src");
exec("chmod -R 775 {$path}/src" );
exec("rm -rf {$path}/src/{$folder}_{$branch}");
chdir("{$path}/src");
// If the dev=1 flag is used when RefreshMarkdownTask is run, a full git clone of the framework repository is kept
// to enable local development of framework and doc.silverstripe.org from within doc.silverstripe.org. Otherwise,
// only a shallow clone of the framework repository is made and all non-markdown files deleted, only allowing viewing
// of documentation files. Note: The --depth 1 option in the git clone command implies the option --single-branch
// only the documentation source files are downloaded, only allowing the viewing of documentation files.
if( $this->request->getVar('dev') ) {
$this->printLine("Performing full clone of " . $remote . "/" . $branch);
exec("git clone -q https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch}");
$this->printLine("Cloning repository {$remote}/{$branch} into assets/src/{$folder}_{$branch}");
exec("git clone --quiet https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch}");
} else {
$this->printLine("Performing shallow clone of " . $remote . "/" . $branch);
exec("git clone -q https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch} --depth 1");
$this->printLine("Deleting non-documentation framework files from shallow clone of " . $remote . "/" . $branch);
chdir("{$path}/src/{$folder}_{$branch}");
$framework_paths = array_merge(glob("*"), glob(".*"));
foreach ($framework_paths as $framework_path) {
if ( $framework_path !== "docs" && $framework_path !=="." && $framework_path !==".." ) {
exec("rm -rf {$framework_path}");
}
}
$this->printLine("Downloading the latest documentation files from repository {$remote}/{$branch} to assets/src/{$folder}_{$branch}");
exec("svn export --quiet https://github.com/{$remote}.git/branches/{$branch}/docs {$folder}_{$branch}/docs");
}
}