From d9c3a5037b1ff6b0e747fee82ab18286a3c794fc Mon Sep 17 00:00:00 2001
From: "Nikita P. Shupeyko" <webyneter@gmail.com>
Date: Sun, 14 May 2017 16:06:32 +0300
Subject: [PATCH] Document Gulp-Docker integration

---
 docs/gulp-with-docker.rst   | 76 +++++++++++++++++++++++++++++++++++++
 docs/index.rst              |  1 +
 docs/nodejs-with-docker.rst | 10 +++--
 3 files changed, 84 insertions(+), 3 deletions(-)
 create mode 100644 docs/gulp-with-docker.rst

diff --git a/docs/gulp-with-docker.rst b/docs/gulp-with-docker.rst
new file mode 100644
index 000000000..1e9b2a184
--- /dev/null
+++ b/docs/gulp-with-docker.rst
@@ -0,0 +1,76 @@
+Gulp with Docker
+================
+
+.. index:: gulp, gulpjs, gulpfile, gulpfilejs, docker, docker-compose
+
+`Gulp`_ support is provided out-of-the-box, ready for use as-is, or with any kind of customizations suiting the specific needs of the project.
+
+.. _`Gulp`: http://gulpjs.com/
+
+*All paths are relative to the generated project's root.*
+
+
+Prerequisites
+-------------
+
+- These :ref:`nodewithdocker-prereq` are satisfied.
+
+
+Overview
+--------
+
+:ref:`nodewithdocker-overview` Node.js integration details first to get the whole picture.
+
+Essential aspects of Gulp integration are
+
+- :code:`./gulpfile.js` with Gulp tasks defined;
+- :code:`./{{ cookiecutter.project_slug }}/static/build/` (build directory) with static assets built via Gulp.
+
+Let us take a closer look at :code:`./gulpfile.js`:
+
+- paths to static assets are provided by :code:`pathsConfig()`;
+- for clarity, related tasks are grouped by :code:`region`:
+    - :code:`images`:
+        - :code:`images`: run image-related tasks in parallel, namely:
+            - :code:`favicons-images`: process favicon images only;
+            - :code:`nonfavicons-images`: process all images except for favicons.
+    - :code:`scripts`:
+        - :code:`scripts`: run script-related tasks in sequence, namely:
+            - :code:`js-scripts`: process js scripts.
+    - :code:`styles`:
+        - :code:`styles`: run script-related tasks in sequence, namely:
+            - :code:`sass-styles`: process SCSS styles;
+            - :code:`css-styles`: process CSS styles.
+    - :code:`build`:
+        - :code:`build`: run :code:`images`, :code:`scripts`, and :code:`styles` in parallel;
+        - :code:`clean-build`: clean up build directory:
+- the :code:`default` task runs the following ones in sequence:
+    - :code:`build`;
+    - :code:`init-browserSync`: initialize `BrowserSync`_;
+    - :code:`watch`: watch static asset files/directories changes, running BrowserSync on any changes.
+
+.. _`BrowserSync`: https://www.browsersync.io/
+
+
+Workflow
+--------
+
+#. [*skip if done*] :ref:`devlocdocker-build-the-stack`;
+#. :ref:`devlocdocker-boot-the-system`.
+
+By default, :code:`gulp` command gets executed immediately after :code:`node`
+container startup (see :code:`./dev.yml` for details) which in turn invokes
+the :code:`default` task, so generally one would not need to run any
+of the aforementioned tasks manually. However, should the need arise,
+oftentimes just a few of the tasks listed above will be used to, for instance,
+straightforwardly :code:`build` all assets
+
+.. code-block:: bash
+
+    $ docker-compose -f dev.yml exec node gulp build
+
+or build :code:`scripts` selectively
+
+.. code-block:: bash
+
+    $ docker-compose -f dev.yml exec node gulp scripts
diff --git a/docs/index.rst b/docs/index.rst
index 7abdf0888..e707365bf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,7 @@ Contents:
    settings
    linters
    nodejs-with-docker
+   gulp-with-docker
    live-reloading-and-sass-compilation
    deployment-on-pythonanywhere
    deployment-on-heroku
diff --git a/docs/nodejs-with-docker.rst b/docs/nodejs-with-docker.rst
index 7b1a70338..468c54087 100644
--- a/docs/nodejs-with-docker.rst
+++ b/docs/nodejs-with-docker.rst
@@ -7,9 +7,11 @@ Node.js with Docker
 
 .. _`Node.js`: https://nodejs.org/en/
 
-*Note, all paths given are relative to the generated project's root.*
+*All paths are relative to the generated project's root.*
 
 
+.. _nodewithdocker-prereq:
+
 Prerequisites
 -------------
 
@@ -17,10 +19,12 @@ Prerequisites
 - These :ref:`devlocdocker-prereq` are met as well.
 
 
+.. _nodewithdocker-overview:
+
 Overview
 --------
 
-Essential aspects of integration are
+Essential aspects of Node.js integration are
 
 - node docker-compose service (:code:`node`) definition in :code:`./dev.yml`;
 - :code:`./compose/node/Dockerfile-dev` defining the :code:`node` image;
@@ -30,7 +34,7 @@ Essential aspects of integration are
 Workflow
 --------
 
-#. :ref:`devlocdocker-build-the-stack`:
+#. [*skip if done*] :ref:`devlocdocker-build-the-stack`:
     - when building :code:`node` image from scratch, dependencies from :code:`package.json` are installed.
 #. :ref:`devlocdocker-boot-the-system`.