merge: Merge master branch

README.md

@@ -7,37 +7,82 @@ Contains the documentation site implementation.
 This section describes the best practices about what and how should be done in order to run the documentation locally.
 
 ### Prerequisites
-- Install Docker (Community Edititon(CE) is enough) - please use the [official Docker installation](https://docs.docker.com/install/) guide. Accept the default installation instructions (use Linux containers, etc.)
+- Install Docker (Community Edititon(CE) is enough) - please use the [official Docker installation](https://docs.docker.com/install/) guide. Accept the default installation instructions (use Linux containers, etc.)    
+  - From the Docker Settings window, share the drive where the documentation repos reside with Docker.
 - Pull the repo to which you want to contribute (we will refer to that repo later as 'MY-REPO')
 
 ### Instructions
-- Clone the current repo 
+- Clone the current (seed) repo 
 ```bash
 git clone git@github.com:telerik/docs-seed.git
 ```
 
-- Go to the directory in which you've pulled it (e.g. D:\Work\docs-seed)
-- Open a terminal of your choice (e.g. gitBash)
-- Run the following command by passing the MY-REPO path:
+- Go to the directory in which you've pulled it (e.g., `D:\Work\docs-seed`)
+- Open a terminal of your choice (e.g., gitBash)
+- Run the following command by passing the MY-REPO path (the **quotes** are mandatory):
 ```bash
 sh copy_local.sh "D:\Work\xaml-docs"
 ```
 
-- Go to the MY-REPO directory and execute the following bash command in the root folder again (where the **Dockerfile** is located)
+- Go to the MY-REPO directory
+- Open a terminal of your choice (e.g., gitBash)
+- Execute the following bash command in the root folder (where the **Dockerfile** is located)
 ```bash
 sh start-docs.sh
 ```
 
-In case you want to add an additional config.yml file, pass it to the above command as follows:
-```bash
-sh start-docs.sh _silverlight.yml
-```
-
 - This is it! You can find the documentation site on server address which is written in the terminal: *http://0.0.0.0:4000/*. If you can't open the previous URL, replace the '0.0.0.0' with 'localhost' - *http://localhost:4000*. 
 > For example, for WPF documentation this would be: http://0.0.0.0:4000/devtools/wpf/
 
-> If you want to stop the web site and the container in which it has been served, navigate to the terminal in which you've executed the previous command and press 'CTRL+C'.
+> If you want to stop the web site and the container in which it has been served, navigate to the terminal in which you've executed the previous command and press `CTRL+C`.
 
+> For WPF and Silverlight, see how to pass an [additional config file](#additional-config-file).
+
+### Troubleshooting
+
+#### Does Not Serve
+
+You executed `sh start-docs.sh` but you did not see any Jekyll output. Instead, the command ended with
+
+>the input device is not a TTY. If you are using mintty, try prefixing the command with 'winpty'
+
+This happens whtn using Git Bash with the MinTTY console. This console does not allow combinations such as `Ctrl+C` to pass to the Docker container and so you get such an error.
+
+The easiest way to **resolve** it is to prefix the command with `winpty`:
+
+```bash
+winpty sh start-docs.sh
+```
+
+An alternative is to re-install Git Bash and choose the default Windows terminal this time. You can read more detailes in the following post: [Docker for Windows: Interactive Sessions in MinTTY Git Bash](https://willi.am/blog/2016/08/08/docker-for-windows-interactive-sessions-in-mintty-git-bash/).
+
+#### Ctrl+C Does not Work
+
+When you want to stop serving the docs, you may have to **repeat** the `Ctrl+C` command or **press** `Enter` after it.
+
+#### .gitignore is Always Modified
+
+The scripts that copy the seed repo to the content repo (MY-REPO), also update the `.gitignore` file so as to avoid creating unstanged changes with work files that must not be commited. If you keep getting the `.gitignore` checked out, see what the change is with the original and commit to your repo the version that matches what the tool generates.
+
+#### Performance
+
+Docker is a resource-intensive tool. If you are not using it on a daily basis, consider preventing it from running on startup. Right click its tray icon > Settings > General, uncheck "Start Docker when you log in". This can save you time when booting up/logging in, but you will need to explicitly start Docker before working on documentation.
+
+Also, it tends to require a lot of HDD space, which may be an issue if you are running it on an SSD drive with limited capacity. You can reduce its quota by opening the Settings dialog > Advanced and either changing the image location, and/or reducing its max size. This also lets you limit its RAM consumption.
+
+### Extra Features
+
+You can benefit from the following features:
+* [additional config file](#additional-config-file)
+* [live sync](#livesync)
+* [build without serve](#only-build)
+
+#### Additional Config File
+
+In case you want to add an additional config.yml file, pass it to the above command as follows:
+```bash
+sh start-docs.sh _silverlight.yml
+```
 #### LiveSync
 To be able to monitor the changes you are making on the built documentation, execute the following command in a new terminal in the root directory of the site:
 ```bash
@@ -45,3 +90,13 @@ sh watch.sh
 ```
 
 > **Prerequisite**: If you haven't yet, please install [Node.js](https://nodejs.org/en/).
+
+#### Only Build
+
+To only run `jekyll build` and not `jekyll serve`, you need to execute the following bash command:
+```bash
+sh build-docs.sh
+```
+
+This can be useful if you want to (or already have) setup local IIS to point to the `_site` folder in your documentation repo. This allows you to also test redirects that `jekyll serve` does not support.
+

_assets/css/icon-font.scss

@@ -2721,6 +2721,26 @@ i {
     content: "\e142";
 }
 
+.t-i-equal:before {
+    content: "\e14a";
+}
+
+.t-i-not-equal:before {
+    content: "\e14b";
+}
+
+.t-i-less-or-equal:before {
+    content: "\e14c";
+}
+
+.t-i-greater-or-equal:before {
+    content: "\e14d";
+}
+
+.t-i-divide:before {
+    content: "\e14e";
+}
+
 .t-i-play:before {
     content: "\e200";
 }

_plugins/code_tabstrip_generator.rb

@@ -1,8 +1,8 @@
 module Reading
   class RegionCodeTabStripGenerator < Jekyll::Generator
 		def generate(site)					
-      @headerSearchPattern = /####\s{1,}(__|\*\*)?\[?(VB|VB.NET|C#|XAML)\]?\s*.*/ 
-			@snippetSearchPattern = /####\s{1,}(__|\*\*)?\[?(VB|VB.NET|C#|XAML)\]?\s*.*\s*(>\n*)*{{region\s.*}}\n*\r*((?!{{endregion}}).*\n*\r*\s*)+?(>?{{endregion}})/ # gets the whole snippet portion - header + region tags + code snippet 			
+			@headerSearchPattern = /####\s{1,}(__|\*\*)?\[?(VB|VB.NET|C#|XAML|SQL|XML)\]?\s*.*/ 
+			@snippetSearchPattern = /####\s{1,}(__|\*\*)?\[?(VB|VB.NET|C#|XAML|SQL|XML)\]?\s*.*\s*(>\n*)*{{region\s.*}}\n*\r*((?!{{endregion}}).*\n*\r*\s*)+?(>?{{endregion}})/ # gets the whole snippet portion - header + region tags + code snippet 			
 			@regionsPattern = /{{region\s.*}}(.*\n*\r*\s*)+?(>?{{endregion}})/ # gets the region tags and the content between them
 			@regionStartPattern = /{{region\s.*}}/
 			@regionEndPattern = /{{endregion}}/
@@ -12,8 +12,8 @@ module Reading
 			@headingEndTag = "</strong></h4>"
 			@separator = "!snippet-separator!"
 			
-		  # fix - https://github.com/aarongustafson/jekyll-webmention_io/commit/5344e44a331efceb3b6b67cb78cc30a333b03c19
-      @converter = site.find_converter_instance(::Jekyll::Converters::Markdown)
+			# fix - https://github.com/aarongustafson/jekyll-webmention_io/commit/5344e44a331efceb3b6b67cb78cc30a333b03c19
+			@converter = site.find_converter_instance(::Jekyll::Converters::Markdown)
 						
 			site.pages.each do |p|	
 				createTabbedCode(p)	
@@ -88,8 +88,8 @@ module Reading
 			end
 		end
 		
-    def getLanguageFromHeader(header)			
-      headerLangPattern = /(__|\*\*)?\[?(VB.NET|VB|C#|XAML)\]?/  # gets the language part of the header (no white spaces). Examples: '__[XAML]' or '__[C#]' or '__XAML', etc.
+		def getLanguageFromHeader(header)			
+			headerLangPattern = /(__|\*\*)?\[?(VB.NET|VB|C#|XAML|SQL|XML)\]?/  # gets the language part of the header (no white spaces). Examples: '__[XAML]' or '__[C#]' or '__XAML', etc.
 			languageString = header[headerLangPattern];
 			if !languageString.nil?							
 				languageString = languageString.gsub("__", "")
@@ -102,7 +102,7 @@ module Reading
 		end
 		
 		def getTrimmedHeader(header)			
-      headerLangPattern = /####\s{1,}(__|\*\*)?\[?(VB.NET|VB|C#|XAML)\]?\s*/ # gets the language part of the header (including white spaces). Examples: '__[XAML] ' or '__[C#] ' or '__XAML ', etc. 
+			headerLangPattern = /####\s{1,}(__|\*\*)?\[?(VB.NET|VB|C#|XAML|SQL|XML)\]?\s*/ # gets the language part of the header (including white spaces). Examples: '__[XAML] ' or '__[C#] ' or '__XAML ', etc. 
 			languageString = header[headerLangPattern];
 			 if !languageString.nil?					
 				header = header.gsub(languageString, "")							

_plugins/figure.rb

@@ -0,0 +1,20 @@
+module Jekyll
+    class FigureTag < Liquid::Tag
+  
+      def initialize(tag_name, text, tokens)
+        super
+        attributes = text.split(',')
+        @number = attributes[0].strip
+        @title = attributes[1].gsub!("\"","").strip
+        @imgSource = attributes[2].gsub!("\"","").strip
+      end
+  
+      def render(context)
+        figure = "<h4><strong>Figure #{@number}: #{@title}</strong></h4>" +
+        "<img src=\"images/#{@imgSource}\" alt=\"#{@title}\" />" 
+        return figure
+      end
+    end
+end
+
+Liquid::Template.register_tag('figure', Jekyll::FigureTag)

build-docs.sh

@@ -4,9 +4,10 @@ config_file="_config.yml"
 if [ ! -z "$1" ]	
   then 	
     config_file+=",$1"
-    echo "Using configuration from: $config_file"	
 fi
 
+echo "Using configuration from: $config_file"	
+
 debug_params=""
 if [ ! -z "$2" ]
   then 

start-docs.sh

@@ -4,9 +4,10 @@ config_file="_config.yml"
 if [ ! -z "$1" ]	
   then 	
     config_file+=",$1"
-    echo "Using configuration from: $config_file"	
 fi
 
+echo "Using configuration from: $config_file"	
+
 rm -rf _site/ .sass-cache .jekyll-cache .asset-cache
 docker pull progressdocs/docs-seed:site
 docker build -t progressdocs/docs-seed:site .