mirror of
https://github.com/silverstripe/doc.silverstripe.org
synced 2024-10-22 15:05:50 +00:00
124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
# doc.silverstripe.org
|
|
|
|
This repository contains the source code powering [SilverStripe's
|
|
developer documentation website](https://docs.silverstripe.org).
|
|
|
|
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)
|
|
modules with minimal configuration.
|
|
|
|
**This repository does NOT contain the most current documentation.**
|
|
|
|
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
|
|
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](https://github.com/SpiritLevel/doc.silverstripe.org):
|
|
|
|
* Ensure you are running the required PHP version (see .platform.yml)
|
|
* 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 shell command
|
|
```
|
|
git clone https://github.com/silverstripe/doc.silverstripe.org path/to/ssdocs
|
|
```
|
|
will clone this repository into `path/to/ssdocs`.
|
|
* From within `path/to/ssdocs`, run the command
|
|
```
|
|
composer install --prefer-source
|
|
```
|
|
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 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/ssdocs`, run the command
|
|
```
|
|
sake dev/tasks/RebuildLuceneDocsIndex flush=1
|
|
```
|
|
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:
|
|
```
|
|
sake dev/tasks/UpdateDocsCronTask
|
|
```
|
|
The cron job `UpdateDocsCronTask` runs the `RefreshMarkdownTask`
|
|
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() {
|
|
return "0 20 * * *"; // runs process() function every day at 8PM
|
|
}
|
|
```
|
|
|
|
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 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 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
|
|
current stable version, set `Stable: true` in
|
|
`app/_config/docsviewer.yml`. Remove the `Stable: true` for all
|
|
versions that are not stable.
|
|
|
|
## Deployment
|
|
|
|
Deployment is via the [SilverStripe Platform](https://www.silverstripe.com/platform/) deployment tool and uses [StackShare](http://www.silverstripe.com/platform/technical/).
|
|
|
|
For platform configuration, see .platform.yml.
|