Fixes #2621: improved theming docs with better wording and module example

docs/guide/theming.md

@@ -8,11 +8,11 @@ time only one theme can be active.
 > Note: Themes usually do not meant to be redistributed since views are too application specific. If you want to
   redistribute customized look and feel consider CSS and JavaScript files in form of [asset bundles](assets.md) instead.
 
-Configuring current theme
--------------------------
+Configuring a theme
+-------------------
 
-Theme configuration is specified via `view` component of the application. So in order to set it up the following should
-be in your application config file:
+Theme configuration is specified via `view` component of the application. In order to set up a theme to work with basic
+application views the following should be in your application config file:
 
 ```php
 'components' => [
@@ -25,9 +25,35 @@ be in your application config file:
 ],
 ```
 
-In the above `pathMap` defines where to look for view files while `baseUrl` defines base URL for resources referenced
-from these files. In our case `pathMap` is `['@app/views' => '@app/themes/basic']` so the themed version
-for a view file `@app/views/site/index.php` will be `@app/themes/basic/site/index.php`.
+In the above `pathMap` defines a map of original paths to themed paths while `baseUrl` defines base URL for
+resources referenced from theme files.
+
+In our case `pathMap` is `['@app/views' => '@app/themes/basic']`. That means that every view in `@app/views` will be
+first searched under `@app/themes/basic` and if a view exists in the theme directory it will be used instead of the
+original view.
+
+For example, with a configuration above a themed version of a view file `@app/views/site/index.php` will be
+`@app/themes/basic/site/index.php`. It basically replaces `@app/views` in `@app/views/site/index.php` with
+`@app/themes/basic`.
+
+### Theming modules
+
+In order to theme modules `pathMap` may look like the following:
+
+```php
+'components' => [
+    'view' => [
+        'theme' => [
+            'pathMap' => [
+                '@app/views' => '@app/themes/basic',
+                '@app/modules' => '@app/themes/basic/modules', // <-- !!!
+            ],
+        ],
+    ],
+],
+```
+
+It will allow you to theme `@app/modules/blog/views/comment/index.php` with `@app/themes/basic/modules/blog/views/comment/index.php`.
 
 ### Theming widgets
 
@@ -38,18 +64,19 @@ view component theme:
 'components' => [
     'view' => [
         'theme' => [
-            'pathMap' => ['@app/widgets/currency/views' => '@app/themes/basic/widgets/currency'],
+            'pathMap' => ['@app/widgets' => '@app/themes/basic/widgets'],
         ],
     ],
 ],
 ```
 
-With the config above you can create themed version of a widget view at `@app/themes/basic/widgets/currency/index.php`.
+With the config above you can create themed version of `@app/widgets/currency/index.php` view in
+`@app/themes/basic/widgets/currency/index.php`.
 
 Using multiple paths
 --------------------
 
-It is possible to map a single path to multiple paths. For example,
+It is possible to map a single path to multiple theme paths. For example,
 
 ```php
 'pathMap' => [