Clean some code and add documentation

_plugins/alerts.rb

@@ -1,7 +1,22 @@
+#alerts.rb generates alert pages using files in _alerts
+#and assign them the 'alert' category.
+
+#This is later used to loop through site.pages in order
+#to display the alert's list in chronological order, both
+#on the "Alerts" page and RSS file.
+
+#If "banner" variable is set in one alert file, site.ALERT
+#variable is set, allowing a clickable alert banner to be
+#displayed in _layouts/base.html .
+
+#If "alias" variable is set in one alert file, a short alias
+#file for the alert (like /android.html) is generated for
+#Bitcoin-Qt non-clickable alerts.
+
 require 'yaml'
 
 module Jekyll
-  
+
   class AlertPage < Page
     def initialize(site, base, lang, srcdir, src, dstdir, dst, date)
       @site = site

_plugins/alphab_for.rb

@@ -1,13 +1,17 @@
-require 'yaml'
-require 'ffi-icu'
-
 #alphab_for allows to loop in an array sorted by the translated value of
-#each key using appropriate collation for the current language. Example :
+#each key using appropriate collation for the current language. In short,
+#this is used to generate translated table of contents.
+
+#Example:
 #{% alphab_for v in page.voc %}
 #  ..
 #{% endalphab_for %}
 
+require 'yaml'
+require 'ffi-icu'
+
 module Jekyll
+
   module AlphabForImpl
     def render(context)
       #load translations files
@@ -61,7 +65,6 @@ module Jekyll
  
   class AlphabForTag < Liquid::For
     include AlphabForImpl
- 
     def collection_to_sort(context)
       return context[@collection_name].dup
     end
@@ -70,6 +73,7 @@ module Jekyll
       'endalphab_for'
     end
   end
+
 end
  
 Liquid::Template.register_tag('alphab_for', Jekyll::AlphabForTag)

_plugins/contributors.rb

@@ -1,57 +1,61 @@
+#contributors.rb fetches Bitcoin-Qt contributors list and set
+#site.project.contributors array. This is later used to
+#display the list of contributors on the "Development" page.
+
 require 'open-uri'
 require 'json'
 require 'yaml'
 
 module Jekyll
 
-	class CategoryGenerator < Generator
-		def fetch_contributors
-			contributors = JSON.parse(open("https://api.github.com/repos/bitcoin/bitcoin/contributors","User-Agent"=>"Ruby/#{RUBY_VERSION}").read)
+  class CategoryGenerator < Generator
+    def fetch_contributors
+      contributors = JSON.parse(open("https://api.github.com/repos/bitcoin/bitcoin/contributors","User-Agent"=>"Ruby/#{RUBY_VERSION}").read)
 
-			contributors.map do |x|
-				x['name'] = x['login'] unless x.has_key?('name')
-				x['name'] = x['login'] if x['name'] == ""
+      contributors.map do |x|
+        x['name'] = x['login'] unless x.has_key?('name')
+        x['name'] = x['login'] if x['name'] == ""
 
-				x
-			end
-		end
+        x
+      end
+    end
 
-		def merge_contributors(contributors, aliases)
-			contributors = contributors.map do |c|
-				c['name'] = aliases[c['name']] if aliases.has_key?(c['name'])
+    def merge_contributors(contributors, aliases)
+      contributors = contributors.map do |c|
+        c['name'] = aliases[c['name']] if aliases.has_key?(c['name'])
 
-				c
-			end
+        c
+      end
 
-			hoaoh = contributors.reduce({}) do |result, item|
-				result.merge({ item['name'] => [item] }) { |key, old, new| old[0]['contributions'] += new[0]['contributions']; old }
-			end
+      hoaoh = contributors.reduce({}) do |result, item|
+        result.merge({ item['name'] => [item] }) { |key, old, new| old[0]['contributions'] += new[0]['contributions']; old }
+      end
 
-			hoaoh.values.map { |sublist|
-				sublist.reduce({}) do |merged,h|
-					merged.merge(h) do |key,old,new| (key=='name' ? old : old+new) end
-				end
-			}.flatten
-		end
+      hoaoh.values.map { |sublist|
+        sublist.reduce({}) do |merged,h|
+          merged.merge(h) do |key,old,new| (key=='name' ? old : old+new) end
+        end
+      }.flatten
+    end
 
-		def generate(site)
-			class << site
-				attr_accessor :primary_devs, :contributors
+    def generate(site)
+      class << site
+        attr_accessor :primary_devs, :contributors
 
-				def site_payload
-					result = super
-					result['site']['project'] = {
-							"primary_devs" => self.primary_devs,
-							"contributors" => self.contributors
-						}
-					result
-				end
-			end
+        def site_payload
+          result = super
+          result['site']['project'] = {
+              "primary_devs" => self.primary_devs,
+              "contributors" => self.contributors
+            }
+          result
+        end
+      end
 
-			site.primary_devs = JSON.parse(open("https://api.github.com/repos/bitcoin/bitcoin/collaborators","User-Agent"=>"Ruby/#{RUBY_VERSION}").read)
-			site.contributors = merge_contributors(fetch_contributors(), site.config['aliases']).sort_by{|c| - c['contributions']}
-		end
+      site.primary_devs = JSON.parse(open("https://api.github.com/repos/bitcoin/bitcoin/collaborators","User-Agent"=>"Ruby/#{RUBY_VERSION}").read)
+      site.contributors = merge_contributors(fetch_contributors(), site.config['aliases']).sort_by{|c| - c['contributions']}
+    end
 
-	end
+  end
 
 end

_plugins/events.rb

@@ -1,3 +1,10 @@
+#events.rb generates blank hidden event pages using files
+#in _events and assign them the 'event' category.
+
+#This is later used to loop through site.pages in order
+#to display the event's list in chronological order, both
+#on the events RSS file and translated events pages.
+
 require 'yaml'
 
 module Jekyll
@@ -17,7 +24,6 @@ module Jekyll
 
   class EventPageGenerator < Generator
     def generate(site)
-      #generate each event page
       Dir.foreach('_events') do |file|
         next if file == '.' or file == '..'
         date = file.split('-')

_plugins/filter_for.rb

@@ -1,10 +1,13 @@
 #filter_for allows to loop in site.pages sorted and filtered
-#by custom page variables. Example :
+#by custom page variables.
+
+#Example:
 #{% filter_for p in site.pages sort_by:date category:release lang:{{page.lang}} %}
 #  ..
 #{% endfilter_for %}
 
 module Jekyll
+
   module SortedForImpl
     def render(context)
       sorted_collection = collection_to_sort context
@@ -52,6 +55,7 @@ module Jekyll
       'endfilter_for'
     end
   end
+
 end
  
 Liquid::Template.register_tag('filter_for', Jekyll::SortedForTag)

_plugins/releases.rb

@@ -1,3 +1,17 @@
+#releases.rb generates release pages using files in _releases
+#and assign them the 'release' category.
+
+#This is later used to loop through site.pages in order
+#to display the release's list in chronological order, both
+#on the "Version history" page and RSS file.
+
+#This plugin also set site.DOWNLOAD_VERSION to the latest
+#available version of Bitcoin-QT, which is used everywhere
+#in the download page.
+
+#Alias redirection pages are generated in /releases to avoid
+#breaking previous links in various websites.
+
 require 'yaml'
 
 module Jekyll

_plugins/sitemap.rb

@@ -1,3 +1,6 @@
+#sitemap.rb generates a sitemap.xml file, which also includes
+#alternate hreflang for each translated version of each page.
+
 require 'yaml'
 require 'cgi'
 
@@ -11,7 +14,6 @@ module Jekyll
 
   class SitemapGenerator < Generator
     def generate(site)
-      
       #Load translations
       locs = {}
       Dir.foreach('_translations') do |file|
@@ -110,7 +112,6 @@ module Jekyll
         sitemap.puts '</urlset>'
       end
       site.static_files << SitemapFile.new(site, site.source, '', 'sitemap.xml')
-
     end
   end
 

_plugins/svg.rb

@@ -1,4 +1,7 @@
+#svg.rb is a workaround to allow built-in jekyll server
+#to serve svg files with jekyll --server.
+
 require 'webrick'
 include WEBrick
 
-WEBrick::HTTPUtils::DefaultMimeTypes.store 'svg', 'image/svg+xml'
+WEBrick::HTTPUtils::DefaultMimeTypes.store 'svg', 'image/svg+xml'

_plugins/templates.rb

@@ -1,13 +1,13 @@
-require 'yaml'
-require 'cgi'
-
-#This plugin generates all translated pages using templates in
+#templates.rb generates all translated pages using templates in
 #_templates. The final file name of each page is defined in 
 #the url section of each translations in _translations.
 
-#If a page is defined in _redirects.yml, this plugin will
+#If a page is defined in _redirects, this plugin will
 #generate a redirection instead of using the template.
 
+require 'yaml'
+require 'cgi'
+
 module Jekyll
 
   class TranslatePage < Page

_plugins/translate.rb

@@ -1,6 +1,3 @@
-require 'yaml'
-require 'cgi'
-
 #translate( id [,category ,lang] )
 #Return translated string using translations files
 
@@ -17,7 +14,11 @@ require 'cgi'
 #/en/vocabulary#wallet when the page is in english or
 #/fr/vocabulaire#porte-monnaie when the page is in french.
 
+require 'yaml'
+require 'cgi'
+
 module Jekyll
+
   class TranslateTag < Liquid::Tag
 
     def initialize(tag_name, id, tokens)
@@ -82,6 +83,7 @@ module Jekyll
       text
     end
   end
+
 end
 
 Liquid::Template.register_tag('translate', Jekyll::TranslateTag)