doc.silverstripe.org/README.md

doc.silverstripe.org

This repository contains the source code powering SilverStripe's developer documentation website.

The source code here primarily consists of the SilverStripe framework and the docsviewer modules with minimal configuration.

This repository does NOT contain the most current documentation.

The documentation files are written in the 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. 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 module.

Installation

To set up a local instance of doc.silverstripe.org:

• Ensure you are running the required PHP version (see .platform.yml)
• Install Composer
• Install sake.
• 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 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. For example, in Ubuntu or Debian, 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, 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. 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. Updated documentation content is uploaded daily at 8PM to doc.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 deployment tool and uses StackShare.

For platform configuration, see .platform.yml.