switched to svn export command for copying documentation files
whitespace update README to include need for subversion editied links and wording editied wording editied wording editied wording editied wording editied wording update README and adjust folder permissions in task whitespace
This commit is contained in:
David Alexander
parent
2f29194db9
commit
7218deb126
90
README.md
90
README.md
|
|
@ -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/).
|
||||
|
|
|
|||
|
|
@ -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");
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue