Merge pull request #295 from picocms/enhancement/isolate-build

Isolate build-related files from source

.gitignore

@@ -10,15 +10,17 @@ desktop.ini
 .DS_Store
 ._*
 
-# Travis
-/build/phpdoc-*/
-/build/phpdoc-*.git/
-
 # Composer
 /composer.lock
 /composer.phar
 /vendor
 
+# phpDocumentor
+/_build/phpdoc/
+/_build/phpdoc.cache/
+/_build/phpdoc-*/
+/_build/phpdoc-*.git/
+
 # User config
 /config/config.php
 

.phpcs.xml

@@ -6,9 +6,14 @@
     </description>
 
     <!--
-        Exclude build/ and vendor/ dirs as well as minified JavaScript files
+        Run on current working directory by default
     -->
-    <exclude-pattern type="relative">^build/</exclude-pattern>
+    <file>.</file>
+
+    <!--
+        Exclude _build/ and vendor/ dirs as well as minified JavaScript files
+    -->
+    <exclude-pattern type="relative">^_build/</exclude-pattern>
     <exclude-pattern type="relative">^vendor/</exclude-pattern>
     <exclude-pattern>*.min.js</exclude-pattern>
 

.phpdoc.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<phpdoc>
+    <title><![CDATA[Pico 1.0 API Documentation]]></title>
+    <parser>
+        <target>_build/phpdoc.cache</target>
+    </parser>
+    <transformer>
+        <target>_build/phpdoc</target>
+    </transformer>
+    <transformations>
+        <template name="clean"/>
+    </transformations>
+    <files>
+        <directory>.</directory>
+        <file>index.php</file>
+        <file>index.php.dist</file>
+
+        <!-- exclude build environment -->
+        <ignore>_build/*</ignore>
+
+        <!-- exclude user config -->
+        <ignore>config/*</ignore>
+        <file>config/config.php.template</file>
+
+        <!-- exclude all plugins -->
+        <ignore>plugins/*</ignore>
+        <file>plugins/DummyPlugin.php</file>
+
+        <!-- exclude vendor dir -->
+        <ignore>vendor/*</ignore>
+    </files>
+</phpdoc>

.travis.yml

@@ -17,10 +17,10 @@ install:
   - composer install
 
 before_script:
-  - export PATH="$TRAVIS_BUILD_DIR/build:$TRAVIS_BUILD_DIR/vendor/bin:$PATH"
+  - export PATH="$TRAVIS_BUILD_DIR/_build:$TRAVIS_BUILD_DIR/vendor/bin:$PATH"
 
 script:
-  - phpcs --standard=phpcs.xml "$TRAVIS_BUILD_DIR"
+  - phpcs --standard=.phpcs.xml "$TRAVIS_BUILD_DIR"
 
 after_success:
   - deploy-phpdoc-branch.sh

CONTRIBUTING.md

@@ -39,11 +39,11 @@ Pico uses the [PSR-2 Coding Standard](http://www.php-fig.org/psr/psr-2/) as defi
 
 For historical reasons we don't use formal namespaces. Markdown files in the `content-sample` folder (the inline documentation) must follow a hard limit of 80 characters line length.
 
-It is recommended to check your code using [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) using the `PSR2` standard using the following command:
+It is recommended to check your code using [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) using Pico's `.phpcs.xml` standard. Use the following command:
 
-    $ ./bin/phpcs --standard=PSR2 [file(s)]
+    $ ./vendor/bin/phpcs --standard=.phpcs.xml [file]...
 
-With this command you can specify a file or folder to limit which files it will check or omit that argument altogether, in which case the current directory is checked.
+With this command you can specify a file or folder to limit which files it will check or omit that argument altogether, in which case the current working directory is checked.
 
 ### Keep documentation in sync
 

_build/deploy-phpdoc-branch.sh

@@ -18,11 +18,13 @@ fi
 PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
 
 generate-phpdoc.sh \
-    "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_BUILD_DIR/.phpdoc.xml" \
+    "$TRAVIS_BUILD_DIR/_build/phpdoc.cache" \
+    "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
     "Pico 1.0 API Documentation ($TRAVIS_BRANCH branch)"
 [ $? -eq 0 ] || exit 1
 
 deploy-phpdoc.sh \
-    "$TRAVIS_REPO_SLUG" "heads/$TRAVIS_BRANCH @ $TRAVIS_COMMIT" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_REPO_SLUG" "heads/$TRAVIS_BRANCH @ $TRAVIS_COMMIT" "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
     "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
 [ $? -eq 0 ] || exit 1

_build/deploy-phpdoc-release.sh

@@ -5,11 +5,13 @@
 PHPDOC_ID="${TRAVIS_BRANCH//\//_}"
 
 generate-phpdoc.sh \
-    "$TRAVIS_BUILD_DIR" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_BUILD_DIR/.phpdoc.xml" \
+    "$TRAVIS_BUILD_DIR/_build/phpdoc.cache" \
+    "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
     "Pico 1.0 API Documentation ($TRAVIS_TAG)"
 [ $? -eq 0 ] || exit 1
 
 deploy-phpdoc.sh \
-    "$TRAVIS_REPO_SLUG" "tags/$TRAVIS_TAG" "$TRAVIS_BUILD_DIR/build/phpdoc-$PHPDOC_ID" \
+    "$TRAVIS_REPO_SLUG" "tags/$TRAVIS_TAG" "$TRAVIS_BUILD_DIR/_build/phpdoc-$PHPDOC_ID" \
     "$TRAVIS_REPO_SLUG" "gh-pages" "phpDoc/$PHPDOC_ID"
 [ $? -eq 0 ] || exit 1

_build/generate-phpdoc.sh

@@ -2,9 +2,10 @@
 set -e
 
 # parameters
-PHPDOC_SOURCE_DIR="$1"
+PHPDOC_CONFIG="$1"
-PHPDOC_TARGET_DIR="$2"
+PHPDOC_CACHE_DIR="$3"
-PHPDOC_TITLE="$3"
+PHPDOC_TARGET_DIR="$4"
+PHPDOC_TITLE="$5"
 
 # print parameters
 echo "Generating phpDocs..."
@@ -14,11 +15,9 @@ printf 'PHPDOC_TITLE="%s"\n' "$PHPDOC_TITLE"
 echo
 
 # generate phpdoc
-phpdoc -d "$PHPDOC_SOURCE_DIR" \
+phpdoc --config "$PHPDOC_CONFIG" \
-    -i "$PHPDOC_SOURCE_DIR/build/" \
+    --cache-folder "$PHPDOC_CACHE_DIR" \
-    -i "$PHPDOC_SOURCE_DIR/vendor/" \
+    --target "$PHPDOC_TARGET_DIR" \
-    -i "$PHPDOC_SOURCE_DIR/plugins/" -f "$PHPDOC_SOURCE_DIR/plugins/DummyPlugin.php" \
-    -t "$PHPDOC_TARGET_DIR" \
     --title "$PHPDOC_TITLE"
 
 echo