Move to GitHub Pages

open-lms-open-source · Jun 2, 2017 · 962403f · 962403f
1 parent a5a9ec4
commit 962403f
Show file tree

Hide file tree

Showing 14 changed files with 247 additions and 130 deletions.
diff --git a/README.md b/README.md
@@ -1,91 +1,12 @@
-# Introduction
-
-The goal of this project is to facilitate the running of tests and code analysis tools against a Moodle plugin in
-[Travis CI](https://travis-ci.org).
-
-Supported tests and code analysis tools:
-* [PHPUnit](https://phpunit.de)
-* [Behat](http://behat.org/)
-* [Moodle Code Checker](https://github.com/moodlehq/moodle-local_codechecker)
-* [Mustache Linting](https://docs.moodle.org/dev/Templates)
-* [Grunt tasks](https://docs.moodle.org/dev/Grunt)
-* [PHP Linting](https://github.com/JakubOnderka/PHP-Parallel-Lint)
-* [PHP Copy/Paste Detector](https://github.com/sebastianbergmann/phpcpd)
-* [PHP Mess Detector](http://phpmd.org)
-
 [![Latest Stable Version](https://poser.pugx.org/moodlerooms/moodle-plugin-ci/v/stable)](https://packagist.org/packages/moodlerooms/moodle-plugin-ci)
 [![Build Status](https://travis-ci.org/moodlerooms/moodle-plugin-ci.svg?branch=master)](https://travis-ci.org/moodlerooms/moodle-plugin-ci)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/moodlerooms/moodle-plugin-ci/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/moodlerooms/moodle-plugin-ci/?branch=master)
 [![Code Coverage](https://scrutinizer-ci.com/g/moodlerooms/moodle-plugin-ci/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/moodlerooms/moodle-plugin-ci/?branch=master)
 [![Total Downloads](https://poser.pugx.org/moodlerooms/moodle-plugin-ci/downloads)](https://packagist.org/packages/moodlerooms/moodle-plugin-ci)
 [![License](https://poser.pugx.org/moodlerooms/moodle-plugin-ci/license)](https://packagist.org/packages/moodlerooms/moodle-plugin-ci)
 
-# Requirements
-
-The requirements for **Version 2** are **PHP 5.6** or later and **Moodle 3.2** or later.
-
-In addition, the plugin being tested must have a [version.php](https://docs.moodle.org/dev/version.php) file
-and `$plugin->component` must be defined within it.
-
-If you need to run your plugin in earlier versions of Moodle, then please use Version 1 of this tool.  Documentation
-and more information about Version 1 can be found in the [v1](https://github.com/moodlerooms/moodle-plugin-ci/tree/v1)
-branch.  Please know that Version 1 is no longer getting new features and may not receive additional updates.
-
-# Getting started
-
-Follow these steps to get your Moodle plugin building in Travis CI.
-
-## Step 1
-
-Sign into [Travis CI](https://travis-ci.org) with your GitHub account. Once you’re signed in, and Travis CI will have
-synchronized your repositories from GitHub.  Go to your [profile](https://travis-ci.org/profile) page and enable Travis CI
-for the plugin you want to build.  Now whenever your plugin receives an update or gets a new pull request, Travis CI will
-run a build to make sure nothing broke.
-
-## Step 2
-
-Copy the [.travis.dist.yml](.travis.dist.yml) file into the root of your plugin and rename it to `.travis.yml`. Now
-might be a good time to review the `.travis.yml` contents and remove anything that is not needed.  See this
-[help document](doc/TravisFileExplained.md) for an explanation about the contents of the this file. Once you have
-added the `.travis.yml` file, commit and push up to GitHub, to trigger a Travis CI build. Check the
-[build status](https://travis-ci.org/repositories) page to see if your build passes or fails.
-
-## Step 3
-
-Congratulations, you are building on Travis CI!  Next steps on your continuous build journey include:
-
-* Reviewing the below documentation to further improve and customize your build.
-* Resolve any build errors you may currently have.  Get to that ever rewarding Green Build status.
-* Show off your build status by [adding the badge to your plugin's README file](https://docs.travis-ci.com/user/status-images/).
-* Write new tests to increase your code coverage.
-* Enjoy your favorite beverage because you no longer have to waste time manually testing your plugin!
-
-# Upgrading
-
-Guides to updating your plugin's `.travis.yml` file to use the latest versions of this tool.
-
-* [Upgrade to 2.0](UPGRADE-2.0.md)
-
-# Documentation
-
-* [Travis CI file explained](doc/TravisFileExplained.md)
-* [Add extra Moodle configs](doc/AddExtraConfig.md)
-* [Add extra plugins](doc/AddExtraPlugins.md)
-* [Ignoring files](doc/IgnoringFiles.md)
-* [Testing a plugin against PHP7](doc/PHP7.md)
-* [Generating code coverage](doc/CodeCoverage.md)
-
-# Usage / Versioning
-
-This project uses [Semantic Versioning](http://semver.org/) for its public API.  The public API for this project
-is defined as the CLI interface of the [moodle-plugin-ci](bin/moodle-plugin-ci) script.  _Everything_ outside of this
-script is considered to be private API and is not guaranteed to follow Semantic Versioning.
-
-The commands ran via the `moodle-plugin-ci` script by default take no arguments.  It is recommended, if at all possible,
-to avoid using arguments to prevent problems with future versions.  Rest assured though that if any arguments are
-modified, it will be in the [change log](CHANGELOG.md) and the version will be bumped appropriately according to
-Semantic Versioning.
-
-# License
+The goal of this project is to facilitate the running of tests and code analysis against a Moodle plugin in
+[Travis CI](https://travis-ci.org).  All of these tests and tools are run everytime a change is pushed to a GitHub
+branch or pull request.
 
-This project is licensed under the GNU GPL v3 or later.  See the [LICENSE](LICENSE) file for details.
+All documentation, guides, change log, etc can be found here: https://moodlerooms.github.io/moodle-plugin-ci/
diff --git a/doc/AddExtraConfig.md → docs/AddExtraConfig.md b/doc/AddExtraConfig.md → docs/AddExtraConfig.md
@@ -1,4 +1,7 @@
-# Adding extra configs to Moodle's configuration file
+---
+layout: page
+title: Adding extra configs to Moodle's configuration file
+---
 
 Sometimes a plugin may require extra config in the Moodle `config.php` file because, for example, it interacts with a
 non-standard service.  This project provides a way to update the `config.php` file with the `add-config` command.  Here

diff --git a/doc/AddExtraPlugins.md → docs/AddExtraPlugins.md b/doc/AddExtraPlugins.md → docs/AddExtraPlugins.md
@@ -1,4 +1,7 @@
-# Adding extra plugins
+---
+layout: page
+title: Adding extra plugins
+---
 
 Sometimes the plugin that you are testing may depend on another plugin or even several other plugins.  This project
 provides a way to Git clone the extra plugins and add them to the Moodle test site. Here is an example of how to use

diff --git a/CHANGELOG.md → docs/CHANGELOG.md b/CHANGELOG.md → docs/CHANGELOG.md
@@ -1,4 +1,8 @@
-# Change Log
+---
+layout: page
+title: Change log
+---
+
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
@@ -24,9 +28,9 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
 - The Composer self update step from `.travis.dist.yml`.
 
 ### Added
-- Defining ignore files per command, see [help document](doc/IgnoringFiles.md) for details. 
+- Defining ignore files per command, see [help document](IgnoringFiles.md) for details. 
 - `moodle-plugin-ci mustache` command which lints your Mustache template files.
-- `moodle-plugin-ci grunt` command which runs Grunt tasks on the plugin. See [help document](doc/TravisFileExplained.md)
+- `moodle-plugin-ci grunt` command which runs Grunt tasks on the plugin. See [help document](TravisFileExplained.md)
   for more details about the command.
 - `moodle-plugin-ci savepoints` command which checks your plugin's upgrade steps.
 - `--dump` option to `behat` command to print Behat HTML failure captures.

diff --git a/doc/CodeCoverage.md → docs/CodeCoverage.md b/doc/CodeCoverage.md → docs/CodeCoverage.md
@@ -1,4 +1,7 @@
-# Generating code coverage
+---
+layout: page
+title: Generating code coverage
+---
 
 Currently, code coverage is only generated for builds that are running on PHP7 or later.  Code coverage generation
 is significantly faster and easier to produce in PHP7.
@@ -22,9 +25,12 @@ script:
   - cat coverage.xml
 ```
 
-You can of course use both options at the same time if you like.
+You can of course use both options at the same time if you like.  Sometimes it is nice to exclude files from code
+coverage stats, for example, CLI scripts that would never be executed by PHPUnit.  You can exclude files by using
+the environment variables described in this [help document](IgnoringFiles.md) in the section about
+command specific ignores.
 
-# Coveralls integration
+## Coveralls integration
 
 Text based coverage and a coverage XML file are fine, but how about a detailed report that tracks coverage over time?
 To do exactly that, this project supports an integration with [Coveralls](https://coveralls.io), though you could

diff --git a/docs/Help.md b/docs/Help.md
@@ -0,0 +1,31 @@
+---
+layout: page
+title: Help
+---
+
+## Change log
+
+Always a good idea to check the [change log](CHANGELOG.md) if something suddenly breaks or behavior
+changed.  Also a good place to look for new goodies.
+
+## Help topics
+
+* [Travis CI file explained](TravisFileExplained.html): every line of the `.travis.yml` file explained.
+* [Add extra Moodle configs](AddExtraConfig.html): how to add extra configs to Moodle `config.php`.
+* [Add extra plugins](AddExtraPlugins.html): how to add plugin dependencies to Moodle.
+* [Ignoring files](IgnoringFiles.html): how to ignore files that might be causing failures.
+* [Testing a plugin against PHP7](PHP7.html): how to test your plugin against PHP7.
+* [Generating code coverage](CodeCoverage.html): how to generate code coverage of your plugin.
+
+## Upgrade guides
+
+* [Upgrading to Version 2](UPGRADE-2.0.md)
+
+
+## Other help
+
+If the above links do not help you, maybe someone
+[asked it already](https://github.com/moodlerooms/moodle-plugin-ci/issues?q=is%3Aissue%20label%3Aquestion).
+If you still cannot find an answer, and Google has failed you as well, then please feel free
+to submit an [new issue](https://github.com/moodlerooms/moodle-plugin-ci/issues/new) providing
+as many relevant details as possible.
diff --git a/doc/IgnoringFiles.md → docs/IgnoringFiles.md b/doc/IgnoringFiles.md → docs/IgnoringFiles.md
@@ -1,11 +1,19 @@
-# Ignoring files
+---
+layout: page
+title: Ignoring files
+---
 
 For some of the code analysis tools, it is important to ignore some files within the plugin because they might not be
 fixable, like a third party library.  The all code analysis commands in this project ignore files and directories
 listed in the [thirdpartylibs.xml](https://docs.moodle.org/dev/Plugin_files#thirdpartylibs.xml) plugin file.
 
+Specifically for the `codechecker` command, you can ignore a single line, a section of a file or the whole file by
+using specific PHP comments.  For details see this
+[PHP_CodeSniffer wiki page](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Advanced-Usage).
+
 In addition, you can ignore additional files by defining `IGNORE_PATHS` and/or `IGNORE_NAMES` environment variables
-in your `.travis.yml` file.  Example:
+in your `.travis.yml` file.  These environment variables wont work for Grunt tasks, but will for everything else.
+Example:
 
 ```yml
 env:
@@ -38,6 +46,7 @@ env:
   - DB=mysqli
 ```
 
-In the above example, we are adding the `cli` path to our ignore paths for the PHPUnit command.  Please note that this
-is a complete override and there is no merging with `IGNORE_PATHS` and `IGNORE_NAMES`.  So, in the above, the PHPUnit
-command would not ignore the file names defined in `IGNORE_NAMES`.
+In the above example, we are adding the `cli` path to our ignore paths for the PHPUnit command (this is also how you
+can ignore files for code coverage).  Please note that this is a complete override and there is no merging with
+`IGNORE_PATHS` and `IGNORE_NAMES`.  So, in the above, the PHPUnit command would not ignore the file names
+defined in `IGNORE_NAMES`.
diff --git a/doc/PHP7.md → docs/PHP7.md b/doc/PHP7.md → docs/PHP7.md
@@ -1,4 +1,7 @@
-# Testing a plugin against PHP7
+---
+layout: page
+title: Testing a plugin against PHP7
+---
 
 Travis CI makes it very easy to test your plugin in multiple versions of PHP and PHP7 is no different.  The only trick
 to testing your plugin in PHP7 is that you must ensure that you are testing against Moodle 3 stable or later as

diff --git a/doc/ReleaseNewVersion.md → docs/ReleaseNewVersion.md b/doc/ReleaseNewVersion.md → docs/ReleaseNewVersion.md
@@ -1,4 +1,7 @@
-# Releasing a new version
+---
+layout: page
+title: Releasing a new version
+---
 
 This is a guide on how to release a new version of this project. Remember that when considering the version number
 to use, that this project follows [Semantic Versioning](http://semver.org/), so bump the version number accordingly.
@@ -7,7 +10,6 @@ Prior to tagging a release, ensure the following have been updated:
 
 * The `CHANGELOG.md` needs to be up-to-date.  In addition, the _Unreleased_ section needs to be updated
   with the version being released.  Also update the _Unreleased_ link at the bottom with the new version number.
-* The `bin/moodle-plugin-ci` needs to be updated with the new version.
 * If this is a new major version, then the `.travis.dist.yml` and `doc/TravisFileExplained.md` need to be updated
   to use the new major version.  Any other version will automatically be used.
 

diff --git a/doc/TravisFileExplained.md → docs/TravisFileExplained.md b/doc/TravisFileExplained.md → docs/TravisFileExplained.md
@@ -1,7 +1,11 @@
-# Travis CI file explained
+---
+layout: page
+title: Travis CI file explained
+---
 
-Below is the [.travis.dist.yml](../.travis.dist.yml) file but with comments added to explain what each section is doing.
-For additional help, see [Travis CI's documentation](http://docs.travis-ci.com/user/getting-started/).
+Below is the [.travis.dist.yml](https://github.com/moodlerooms/moodle-plugin-ci/blob/master/.travis.dist.yml)
+file but with comments added to explain what each section is doing. For additional help,
+see [Travis CI's documentation](http://docs.travis-ci.com/user/getting-started/).
 
 ```yaml
 # This is the language of our project.
@@ -10,22 +14,24 @@ language: php
 # This tells Travis CI to use its new architecture.  Everything is better!
 sudo: false
 
-# Installs updated version of PostgreSQL and installs extra APT packages.  Java 8 is only required for Mustache command.
+# Installs updated version of PostgreSQL and installs extra APT packages.
+# Java 8 is only required for Mustache command.
 addons:
   postgresql: "9.3"
   apt:
     packages:
       - oracle-java8-installer
       - oracle-java8-set-default
 
-# This tells Travis CI to cache NPM's and Composer's caches.  Speeds up build times.
+# Cache NPM's and Composer's caches to speed up build times.
 cache:
   directories:
     - $HOME/.composer/cache
     - $HOME/.npm
 
-# Determines which versions of PHP to test our project against.  Each version listed
-# here will create a separate build and run the tests against that version of PHP.
+# Determines which versions of PHP to test our project against.  Each version
+# listed here will create a separate build and run the tests against that
+# version of PHP.
 php:
  - 5.6
  - 7.0
@@ -36,10 +42,11 @@ env:
  global:
 # This line determines which version of Moodle to test against.
   - MOODLE_BRANCH=MOODLE_32_STABLE
-# This matrix is used for testing against multiple databases.  So for each version of
-# PHP being tested, one build will be created for each database listed here.  EG: for
-# PHP 5.6, one build will be created using PHP 5.6 and pgsql.  In addition, another
-# build will be created using PHP 5.6 and mysqli.
+# This matrix is used for testing against multiple databases.  So for
+# each version of PHP being tested, one build will be created for each
+# database listed here.  EG: for PHP 5.6, one build will be created
+# using PHP 5.6 and pgsql.  In addition, another build will be created
+# using PHP 5.6 and mysqli.
  matrix:
   - DB=pgsql
   - DB=mysqli
@@ -66,7 +73,7 @@ install:
 #    - Create Moodle config.php, database, etc.
 #    - Copy your plugin(s) into Moodle.
 #    - Run Composer install within Moodle.
-#    - Run NPM install within Moodle and in your plugin if it has a "package.json" file.
+#    - Run NPM install in Moodle and in your plugin if it has a "package.json".
 #    - Run "grunt ignorefiles" within Moodle to update ignore file lists.
 #    - If your plugin has Behat features, then Behat will be setup.
 #    - If your plugin has unit tests, then PHPUnit will be setup.
@@ -78,29 +85,38 @@ install:
 script:
 # This step lints your PHP files to check for syntax errors.
   - moodle-plugin-ci phplint
-# This step runs the PHP Copy/Paste Detector on your plugin. This helps to find code duplication.
+# This step runs the PHP Copy/Paste Detector on your plugin.
+# This helps to find code duplication.
   - moodle-plugin-ci phpcpd
-# This step runs the PHP Mess Detector on your plugin. This helps to find potential
-# problems with your code which can result in refactoring opportunities.
+# This step runs the PHP Mess Detector on your plugin. This helps to find
+# potential problems with your code which can result in
+# refactoring opportunities.
   - moodle-plugin-ci phpmd
-# This step runs the Moodle Code Checker to make sure that your plugin conforms to the
-# Moodle coding standards.  It is highly recommended that you keep this step.
+# This step runs the Moodle Code Checker to make sure that your plugin
+# conforms to the Moodle coding standards.  It is highly recommended
+# that you keep this step.
   - moodle-plugin-ci codechecker
-# This step runs some light validation on the plugin file structure and code.  Validation can be plugin specific.
+# This step runs some light validation on the plugin file structure
+# and code.  Validation can be plugin specific.
   - moodle-plugin-ci validate
 # This step validates your plugin's upgrade steps.
   - moodle-plugin-ci savepoints
 # This step validates the HTML and Javascript in your Mustache templates.
   - moodle-plugin-ci mustache
-# This step runs Grunt tasks on the plugin.  By default, it tries to run tasks relevant to your plugin and Moodle
-# version, but you can run specific tasks by passing them as options, EG: moodle-plugin-ci grunt -t task1 -t task2 
+# This step runs Grunt tasks on the plugin.  By default, it tries to run
+# tasks relevant to your plugin and Moodle version, but you can run
+# specific tasks by passing them as options,
+# EG: moodle-plugin-ci grunt -t task1 -t task2 
   - moodle-plugin-ci grunt
-# This step runs the PHPUnit tests of your plugin.  If your plugin has PHPUnit tests,
-# then it is highly recommended that you keep this step.
+# This step runs the PHPUnit tests of your plugin.  If your plugin has
+# PHPUnit tests, then it is highly recommended that you keep this step.
   - moodle-plugin-ci phpunit
-# This step runs the Behat tests of your plugin.  If your plugin has Behat tests, then it is highly recommended that
-# you keep this step.  There are two important options that you may want to use:
-#   - The auto rerun option allows you to rerun failures X number of times, default is 2, EG usage: --auto-rerun 3
-#   - The dump option allows you to print the failure HTML to the console, handy for debugging, EG usage: --dump
+# This step runs the Behat tests of your plugin.  If your plugin has
+# Behat tests, then it is highly recommended that you keep this step.
+# There are two important options that you may want to use:
+#   - The auto rerun option allows you to rerun failures X number of times,
+#     default is 2, EG usage: --auto-rerun 3
+#   - The dump option allows you to print the failure HTML to the console,
+#     handy for debugging, EG usage: --dump
   - moodle-plugin-ci behat
 ```
diff --git a/UPGRADE-2.0.md → docs/UPGRADE-2.0.md b/UPGRADE-2.0.md → docs/UPGRADE-2.0.md
@@ -1,4 +1,7 @@
-# Upgrading from 1.X to 2.0
+---
+layout: page
+title: Upgrading from 1.X to 2.0
+---
 
 This document outlines the steps one should take when upgrading to the new major version.
 
@@ -12,10 +15,11 @@ Detailed information about what changed in Version 2 can be found in the [change
 
 ## Step 3: Review the Travis CI configuration file 
 
-Review the updated [.travis.dist.yml](.travis.dist.yml) and update your `.travis.yml` file in your plugin.
-For detailed information about the contents of `.travis.dist.yml` file, please see this
-[help document](doc/TravisFileExplained.md).  **Please carefully** review the updated `.travis.dist.yml` as
-some steps have been removed and others added, like installation of Java 8, upgrade of NodeJS, etc.
+Review the updated [.travis.dist.yml](https://github.com/moodlerooms/moodle-plugin-ci/blob/master/.travis.dist.yml)
+and update your `.travis.yml` file in your plugin. For detailed information about the contents of `.travis.dist.yml`
+file, please see this [help document](TravisFileExplained.md).  **Please carefully** review the updated
+`.travis.dist.yml` as some steps have been removed and others added, like installation of Java 8,
+upgrade of NodeJS, etc.
 
 ## FAQ