Merge pull request #131 from SpiritLevel/master
switched to svn export command for copying documentation files
This commit is contained in:
commit
d92ce25c5c
90
README.md
90
README.md
|
@ -1,58 +1,80 @@
|
||||||
# doc.silverstripe.org
|
# 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)
|
[framework](https://github.com/silverstripe/silverstripe-framework)
|
||||||
and the [docsviewer](https://github.com/silverstripe/silverstripe-docsviewer)
|
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
|
The documentation files are written in the
|
||||||
stored in each framework repository within a `docs` folder. For
|
[markdown](https://docs.silverstripe.org/en/2.4/misc/ss-markdown/)
|
||||||
example, the documentation for the master branch of the SilverStripe
|
format and the most current versions of these files and are not stored
|
||||||
framework is stored in
|
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).
|
[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
|
As described below in the **Installation** section, one must first
|
||||||
and re-index fresh versions of the documentation files from the framework
|
download the latest versions of the documentation markdown files from
|
||||||
repositories before being able to view the latest content.
|
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
|
For adding functionality or editing the style of the documentation, see the
|
||||||
[docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module.
|
[docsviewer](https://github.com/silverstripe/silverstripe-docsviewer) module.
|
||||||
|
|
||||||
## Installation
|
## 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 [Composer](https://docs.silverstripe.org/en/getting_started/composer).
|
||||||
* Install [sake](https://docs.silverstripe.org/en/developer_guides/cli).
|
* 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`.
|
will clone this repository into `path/to/ssdocs`.
|
||||||
* From within `path/to/webroot/ssdocs`, run the command
|
* From within `path/to/ssdocs`, run the command
|
||||||
```
|
```
|
||||||
composer install --prefer-source
|
composer install --prefer-source
|
||||||
```
|
```
|
||||||
to grab the modules, in particular, the [docsviewer](http://github.com/silverstripe/silverstripe-docsviewer) module.
|
to install all required modules, in particular, the [docsviewer](http://github.com/silverstripe/silverstripe-docsviewer) module.
|
||||||
* From within `path/to/webroot/ssdocs`, run the command
|
* 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
|
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
|
sake dev/tasks/RefreshMarkdownTask flush=1 dev=1
|
||||||
```
|
```
|
||||||
to get the full git repositories.
|
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
|
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.
|
* 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
|
## Automation
|
||||||
|
|
||||||
Refreshing and re-indexing the documentation markdown files can be automated. From within `path/to/webroot/ssdocs`, run the command:
|
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
|
sake dev/tasks/UpdateDocsCronTask
|
||||||
```
|
```
|
||||||
The cron job `UpdateDocsCronTask` runs the `RefreshMarkdownTask`
|
The cron job `UpdateDocsCronTask` runs the `RefreshMarkdownTask`
|
||||||
and `RebuildLuceneDocsIndex` tasks every day at 8PM. This can be
|
and `RebuildLuceneDocsIndex` tasks every day at 8PM. This execution schedule can be
|
||||||
altered by editing `UpdateDocsCronTask.php` and changing the scheduling
|
altered by editing `UpdateDocsCronTask.php`, found in the `apps/code` folder, and changing the scheduling
|
||||||
function:
|
function:
|
||||||
```
|
```
|
||||||
public function getSchedule() {
|
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
|
## Contribution
|
||||||
|
|
||||||
To contribute an improvement to the https://docs.silverstripe.org functionality or
|
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.
|
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
|
If you wish to edit the documentation content, submit a pull request
|
||||||
Github project. Updated documentation content is regularly uploaded to https://docs.silverstripe.org via a cron job.
|
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
|
If you are adding a new version of the documentation, you must
|
||||||
register it in both `app/_config/docs-repositories.yml` and
|
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
|
current stable version, set `Stable: true` in
|
||||||
`app/_config/docsviewer.yml`. Remove the `Stable: true` setting for
|
`app/_config/docsviewer.yml`. Remove the `Stable: true` for all
|
||||||
all versions that are not stable.
|
versions that are not stable.
|
||||||
|
|
||||||
## Deployment
|
## 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/).
|
||||||
|
|
|
@ -36,11 +36,14 @@ class RefreshMarkdownTask extends BuildTask
|
||||||
public function run($request)
|
public function run($request)
|
||||||
{
|
{
|
||||||
$this->request = $request;
|
$this->request = $request;
|
||||||
$this->printLine("Refreshing markdown files...");
|
|
||||||
$repositories = $this->getRepositories();
|
$repositories = $this->getRepositories();
|
||||||
foreach ($repositories as $repository) {
|
foreach ($repositories as $repository) {
|
||||||
$this->cloneRepository($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();
|
$path = $this->getPath();
|
||||||
|
|
||||||
exec("mkdir -p {$path}/src");
|
exec("mkdir -p {$path}/src");
|
||||||
|
exec("chmod -R 775 {$path}/src" );
|
||||||
exec("rm -rf {$path}/src/{$folder}_{$branch}");
|
exec("rm -rf {$path}/src/{$folder}_{$branch}");
|
||||||
chdir("{$path}/src");
|
chdir("{$path}/src");
|
||||||
|
|
||||||
// If the dev=1 flag is used when RefreshMarkdownTask is run, a full git clone of the framework repository is kept
|
// 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,
|
// 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
|
// only the documentation source files are downloaded, only allowing the viewing of documentation files.
|
||||||
// of documentation files. Note: The --depth 1 option in the git clone command implies the option --single-branch
|
|
||||||
|
|
||||||
if( $this->request->getVar('dev') ) {
|
if( $this->request->getVar('dev') ) {
|
||||||
$this->printLine("Performing full clone of " . $remote . "/" . $branch);
|
$this->printLine("Cloning repository {$remote}/{$branch} into assets/src/{$folder}_{$branch}");
|
||||||
exec("git clone -q https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch}");
|
exec("git clone --quiet https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch}");
|
||||||
} else {
|
} else {
|
||||||
$this->printLine("Performing shallow clone of " . $remote . "/" . $branch);
|
$this->printLine("Downloading the latest documentation files from repository {$remote}/{$branch} to assets/src/{$folder}_{$branch}");
|
||||||
exec("git clone -q https://github.com/{$remote}.git {$folder}_{$branch} --branch {$branch} --depth 1");
|
exec("svn export --quiet https://github.com/{$remote}.git/branches/{$branch}/docs {$folder}_{$branch}/docs");
|
||||||
$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}");
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
}
|
}
|
||||||
|
|
Loading…
Reference in New Issue