cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From akurdyu...@apache.org
Subject [3/9] docs commit: Split language and version selector dropdown on two parts Now languages are hardcoded during generation, and versions populated from shared script. Language population should also take data from some shared file, and versions should be
Date Sun, 09 Aug 2015 12:43:19 GMT
Split language and version selector dropdown on two parts
Now languages are hardcoded during generation, and versions populated from shared script.
Language population should also take data from some shared file, and versions should be pregenerated
to have better UI experience on slow networks.


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/a2ee1768
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/a2ee1768
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/a2ee1768

Branch: refs/heads/master
Commit: a2ee176844e16b030ca2f7121c9c7cf4dc1c393f
Parents: 396503a
Author: Andrey Kurdyumov <kant2002@gmail.com>
Authored: Thu Aug 6 19:29:10 2015 +0600
Committer: Andrey Kurdyumov <kant2002@gmail.com>
Committed: Thu Aug 6 19:29:10 2015 +0600

----------------------------------------------------------------------
 README.md                        | 43 +++++++++++++++++++----
 lib/cordova/post/versionmenu.js  | 45 +++++++++++++++++++++---
 lib/docs_generator.js            | 29 ++++++++++++++++
 template/docs/default/index.css  |  4 +++
 template/docs/default/index.html |  9 +++--
 template/docs/default/index.js   | 65 ++++++++++++++++++++++++++++++++++-
 template/docs/es/index.html      |  9 +++--
 template/docs/fr/index.html      |  9 +++--
 template/docs/jp/index.html      |  9 +++--
 template/docs/ru/index.html      |  9 +++--
 10 files changed, 210 insertions(+), 21 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 6446548..f27be98 100644
--- a/README.md
+++ b/README.md
@@ -18,8 +18,35 @@ File Structure
     docs/LANGUAGE/VERSION
     docs/LANGUAGE/VERSION/cordova/
     docs/LANGUAGE/VERSION/guide/platforms/PLATFORMNAME/
+    docs/LANGUAGE/versions.js
+    docs/commondata.js
+    
+That's file structure of docs how they appears on the server.
+When generated these content could be found in the `public` folder, inside the project.
+
+`versions.js` is file which contains array of all doc versions for specific language. That
file would be loaded by website JS 
+and allow older docs to be aware more recent version of docs. That's limit need to publish
whole docs as single piece.
+
+`commondata.js` is file which contains array of all languages supported by documentation
now, also . That file would be loaded by website JS 
+and allow older docs to be aware more recent translation effort of the docs and more recent
version of docs. That's limit need to publish whole docs as single piece.
+    
+Source files structure
+----------------------
+    docs/
+    docs/LANGUAGE
+    docs/LANGUAGE/VERSION
+    docs/LANGUAGE/VERSION/cordova/
+    docs/LANGUAGE/VERSION/guide/platforms/PLATFORMNAME/
     template/docs/default
     template/docs/LANGUAGE
+    
+Docs consists from two parts - Source files for each language and HTML/CSS/JS templates for
the docs.
+The docs for all languages except English translated using [Crowdin](http://crowdin.com/project/cordova/).
Please don't edit these in this repository, 
+these changes would be overridden by export from Crowdin.
+
+Templates are set of HTML/CSS/JS files. By default used template within `template/docs/default`.
When generating docs for any language
+to the temporary folder first copied content of the default template, then copied files from
specific language. That's allow override some settings for the templates 
+without need to duplicate all assets in each template.
 
 Contributing to the Documentation
 ---------------------------------
@@ -43,15 +70,17 @@ Pull requests are welcome!
 
 We appreciate the use of topic branches.
 
-    git checkout -b issue_23
+    git checkout -b CB-9923
 
     # code
 
-    git commit -m "Issue 23: Fix a bad bug."
+    git commit -m "CB-9923: Fix a bad bug."
 
-    git push origin issue_23
+    git push origin CB-9923
 
-    # send pull request from branch issue_23 to cordova:master
+    # send pull request from branch CB-9923 to cordova:master
+    
+Please don't send pull requests for the languages other then English, use [Crowdin](http://crowdin.com/project/cordova/)
 
 ### Adding a Language
 
@@ -68,11 +97,13 @@ Cordova language administrators, don't forget these steps:
 __1. config.json__
 
 For each language and version, there is a `config.json` that defines the name of the language
and
-how to merge the files.
+how to merge the files. Merge files a still implemented, but not used.
 
 __2. Customizing HTML template__
 
-Each language can override the default template in `template/docs/LANGUAGE`.
+Each language can override the default template in `template/docs/LANGUAGE`. 
+You don't need copy content of whole `template/docs/default` inside language specific template,
+you just override only these files which you need modify. Other files would be picked up
from `template/docs/default`.
 
 ### Editorial Guidelines
 

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/lib/cordova/post/versionmenu.js
----------------------------------------------------------------------
diff --git a/lib/cordova/post/versionmenu.js b/lib/cordova/post/versionmenu.js
index 84bda9b..0adfef4 100644
--- a/lib/cordova/post/versionmenu.js
+++ b/lib/cordova/post/versionmenu.js
@@ -38,11 +38,12 @@ var VersionMenu = (function () {
         this.stage = "Populate version menu";
         if (languages === null) {
             languages = [];
-            versions = [];
+            versions = {};
             this.buildVersionsData();
         }
         
         this.generatedMenu = this.generateMenu();
+        this.generatedLanguageMenu = this.generateLanguageMenu();
     }
 
     VersionMenu.prototype.run = function (file, $) {
@@ -54,12 +55,22 @@ var VersionMenu = (function () {
             console.info("Building version menu for file " + file);
         }
 
-        var element;
+        var element,
+            scriptTag,
+            currentPageSettings;
 
-        element = $('#header small select').first();
-        this.generatedMenu.forEach(function (optionGroup) {
+        element = $('#header small select#language').first();
+        this.generatedLanguageMenu.forEach(function (optionGroup) {
             element.append(optionGroup).append("\n");
         });
+        element = $('head').first();
+        currentPageSettings = {
+            lang: this.options.lang,
+            version: this.options.version
+        };
+        scriptTag = cheerio("<script></script>")
+        scriptTag.text("var settings = " + JSON.stringify(currentPageSettings) + ";");
+        element.append(scriptTag);
     };
 
     VersionMenu.prototype.buildVersionsData = function () {
@@ -138,6 +149,32 @@ var VersionMenu = (function () {
         return result;
     };
 
+    VersionMenu.prototype.generateLanguageMenu = function () {
+        var result = [],
+            langGroup,
+            lang,
+            mapper,
+            key;
+
+        mapper = function (item) {
+            return item;
+        };
+
+        for (key in languages) {
+            if (languages.hasOwnProperty(key)) {
+                lang = languages[key].lang;
+                langGroup = cheerio("<option></option>");
+                langGroup.append("\n");
+                langGroup.attr('label', languages[key].label);
+                langGroup.attr('value', lang);
+
+                result.push(langGroup);
+            }
+        }
+
+        return result;
+    };
+
     return VersionMenu;
 }());
 module.exports = VersionMenu;

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/lib/docs_generator.js
----------------------------------------------------------------------
diff --git a/lib/docs_generator.js b/lib/docs_generator.js
index 8ea7a20..cc5b2cf 100644
--- a/lib/docs_generator.js
+++ b/lib/docs_generator.js
@@ -132,10 +132,39 @@ var DocsGenerator = (function () {
                         timing: timing
                     };
                 });
+
+                var output_path = path.join(self.output_directory, language_dir),
+                    input_path = path.join(self.input_directory, language_dir),
+                    options = {
+                        lang: language_dir,
+                        verbose: verbose_mode,
+                        timing: timing
+                    };
+                self.options = options;
+            });
+            self.captureExecutionTime("Generate languages list", 0, function () {
+                try {
+                    self.buildLanguageList(self.input_directory, self.output_directory);
+                } catch (e) {
+                    console.warn("=================================================");
+                    console.warn("ERROR: Generating the Cordova Documentation Language List
failed.");
+                    console.warn(e.stack || e.toString());
+                    console.warn("=================================================");
+                }
             });
         });
     };
 
+    DocsGenerator.prototype.buildLanguageList = function (input_path, output_path, options)
{
+        var languages = fs.readdirSync(input_path);
+        var versions = {};
+        languages.forEach(function (language_dir) {
+            var langVersions = fs.readdirSync(path.join(input_path, language_dir));;
+            versions[language_dir] = langVersions;
+        });
+        fs.writeFileSync(path.join(output_path, "commondata.js"), "var languages = " + JSON.stringify(languages)
+ "; var versions = " + JSON.stringify(versions));
+    }
+
     DocsGenerator.prototype.process = function (input_path, output_path, options) {
         if (options.verbose > 0) {
             console.log("Clearing output directory for lang " + options.lang + " and version
" + options.version);

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/default/index.css
----------------------------------------------------------------------
diff --git a/template/docs/default/index.css b/template/docs/default/index.css
index 713ebe5..c5685c4 100644
--- a/template/docs/default/index.css
+++ b/template/docs/default/index.css
@@ -133,6 +133,10 @@ h1, ul, li {
   text-shadow:-1px 1px 1px #666666;
 }
 
+select#version {
+    width: 60px;
+}
+
 #sidebar .vertical_divider {
   background-color:#CCCCCC;
   bottom:0px;

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/default/index.html
----------------------------------------------------------------------
diff --git a/template/docs/default/index.html b/template/docs/default/index.html
index 9bc746e..5f26a7c 100644
--- a/template/docs/default/index.html
+++ b/template/docs/default/index.html
@@ -30,12 +30,18 @@
         <link rel="stylesheet" type="text/css" href="phone.css" media="only screen and
(max-device-width: 414px)">
         <link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and
(max-device-width: 1024px)">
         <link rel="stylesheet" type="text/css" href="prettify/prettify.css" />
+        <script type="text/javascript" src="../../commondata.js"></script>
+        <script type="text/javascript" src="index.js"></script>
     </head>
     <body>
         <div id="header">
             <h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
             <small>
-                <select></select>
+                <select id="language"></select>
+                <select id="version"></select>
+                <script>
+                setupLanguageSelect(); setupVersionSelect();
+                </script>
             </small>
         </div>
         <div id="subheader">
@@ -54,7 +60,6 @@
         </div>
 
         <!-- Functionality and Syntax Highlighting -->
-        <script type="text/javascript" src="index.js"></script>
         <script type="text/javascript" src="prettify/prettify.js"></script>
     </body>
 </html>

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/default/index.js
----------------------------------------------------------------------
diff --git a/template/docs/default/index.js b/template/docs/default/index.js
index 85fcdad..374ec60 100644
--- a/template/docs/default/index.js
+++ b/template/docs/default/index.js
@@ -39,10 +39,73 @@ ga('send', 'pageview');
     }, false);
 })();
 
+function changeLanguageOrVersion(language, version, missingVersion) {
+    var currentFile = (window.location.href.match(/\/[^\/]*$/) || ['/index.html'])[0];
+
+    // Uncomment to also jump to the same page. However, the server should handle missing
page
+    // window.location.href = '../../' + language + '/' + version + currentFile;
+    var sameFile = '../../' + language + '/' + version + currentFile;
+    var testForSameVersion = true;
+    if (testForSameVersion && window.location.protocol !== "file:") {
+        var xmlhttp = new XMLHttpRequest()
+        xmlhttp.open('GET', sameFile, false);
+        xmlhttp.send(null);
+        console.log(xmlhttp);
+        if(xmlhttp.status == 200) {
+            window.location.href = sameFile;
+        } else {
+            window.location.href = '../../' + language + '/' + version + '/index.html';
+        }
+    } else {
+        window.location.href = sameFile;
+    }
+}
+
+function setupLanguageSelect() {
+    var languageElement = document.getElementById('language');
+    languageElement.value = settings.lang;
+    languageElement.addEventListener('change', function(e) {
+        var language    = languageElement.value;
+        var languageVersions = versions[language];
+        var hasVersionInLanguage = languageVersions.filter(function (versionString) {
+            versionString === settings.version;
+        }).length > 0;
+        if (hasVersionInLanguage) {
+            var version = settings.version;
+            var missingVersion = false;
+        } else {
+            var version = "edge";
+            var missingVersion = true;
+        }
+
+        changeLanguageOrVersion(language, version, missingVersion);
+    }, false);
+}
+
+function setupVersionSelect() {
+    var versionElement = document.getElementById('version');
+    var languageVersions = versions[settings.lang];
+    languageVersions.reverse().forEach(function (version) {
+        var optionElement = document.createElement("option");
+        optionElement.value = version;
+        optionElement.innerHTML = version;
+        versionElement.appendChild(optionElement);
+    });
+    versionElement.value = settings.version;
+    versionElement.addEventListener('change', function(e) {
+        var languageElement = document.getElementById('language');
+        var language = languageElement.value;
+        var version = versionElement.value;
+
+        changeLanguageOrVersion(language, version, false);
+    }, false);
+}
+
 //
 // Version and Language <select>
 //
 (function() {
+    
     window.addEventListener('load', function() {
         document.getElementById('header').getElementsByTagName('select')[0].addEventListener('change',
function(e) {
             var $select     = this.options[this.selectedIndex];
@@ -52,7 +115,7 @@ ga('send', 'pageview');
 
             // Uncomment to also jump to the same page. However, the server should handle
missing page
             // window.location.href = '../../' + language + '/' + version + currentFile;
-            window.location.href = '../../' + language + '/' + version + '/index.html';
+            //window.location.href = '../../' + language + '/' + version + '/index.html';
         }, false);
     }, false);
 })();

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/es/index.html
----------------------------------------------------------------------
diff --git a/template/docs/es/index.html b/template/docs/es/index.html
index 13f38c8..a03e288 100644
--- a/template/docs/es/index.html
+++ b/template/docs/es/index.html
@@ -30,12 +30,18 @@
         <link rel="stylesheet" type="text/css" href="phone.css" media="only screen and
(max-device-width: 414px)">
         <link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and
(max-device-width: 1024px)">
         <link rel="stylesheet" type="text/css" href="prettify/prettify.css" />
+        <script type="text/javascript" src="../../commondata.js"></script>
+        <script type="text/javascript" src="index.js"></script>
     </head>
     <body>
         <div id="header">
             <h1><a href="index.html">Documentación Apache <strong>Cordova</strong></a></h1>
             <small>
-                <select></select>
+                <select id="language"></select>
+                <select id="version"></select>
+                <script>
+                setupLanguageSelect(); setupVersionSelect();
+                </script>
             </small>
         </div>
         <div id="subheader">
@@ -54,7 +60,6 @@
         </div>
 
         <!-- Functionality and Syntax Highlighting -->
-        <script type="text/javascript" src="index.js"></script>
         <script type="text/javascript" src="prettify/prettify.js"></script>
     </body>
 </html>

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/fr/index.html
----------------------------------------------------------------------
diff --git a/template/docs/fr/index.html b/template/docs/fr/index.html
index bf26e46..2c9d7fc 100644
--- a/template/docs/fr/index.html
+++ b/template/docs/fr/index.html
@@ -30,12 +30,18 @@
         <link rel="stylesheet" type="text/css" href="phone.css" media="only screen and
(max-device-width: 414px)">
         <link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and
(max-device-width: 1024px)">
         <link rel="stylesheet" type="text/css" href="prettify/prettify.css" />
+        <script type="text/javascript" src="../../commondata.js"></script>
+        <script type="text/javascript" src="index.js"></script>
     </head>
     <body>
         <div id="header">
             <h1><a href="index.html">Documentation Apache <strong>Cordova</strong></a></h1>
             <small>
-                <select></select>
+                <select id="language"></select>
+                <select id="version"></select>
+                <script>
+                setupLanguageSelect(); setupVersionSelect();
+                </script>
             </small>
         </div>
         <div id="subheader">
@@ -54,7 +60,6 @@
         </div>
 
         <!-- Functionality and Syntax Highlighting -->
-        <script type="text/javascript" src="index.js"></script>
         <script type="text/javascript" src="prettify/prettify.js"></script>
     </body>
 </html>

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/jp/index.html
----------------------------------------------------------------------
diff --git a/template/docs/jp/index.html b/template/docs/jp/index.html
index 9bc746e..5f26a7c 100644
--- a/template/docs/jp/index.html
+++ b/template/docs/jp/index.html
@@ -30,12 +30,18 @@
         <link rel="stylesheet" type="text/css" href="phone.css" media="only screen and
(max-device-width: 414px)">
         <link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and
(max-device-width: 1024px)">
         <link rel="stylesheet" type="text/css" href="prettify/prettify.css" />
+        <script type="text/javascript" src="../../commondata.js"></script>
+        <script type="text/javascript" src="index.js"></script>
     </head>
     <body>
         <div id="header">
             <h1><a href="index.html">Apache <strong>Cordova</strong>
Documentation</a></h1>
             <small>
-                <select></select>
+                <select id="language"></select>
+                <select id="version"></select>
+                <script>
+                setupLanguageSelect(); setupVersionSelect();
+                </script>
             </small>
         </div>
         <div id="subheader">
@@ -54,7 +60,6 @@
         </div>
 
         <!-- Functionality and Syntax Highlighting -->
-        <script type="text/javascript" src="index.js"></script>
         <script type="text/javascript" src="prettify/prettify.js"></script>
     </body>
 </html>

http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/a2ee1768/template/docs/ru/index.html
----------------------------------------------------------------------
diff --git a/template/docs/ru/index.html b/template/docs/ru/index.html
index 60a3c20..1c50b80 100644
--- a/template/docs/ru/index.html
+++ b/template/docs/ru/index.html
@@ -35,12 +35,18 @@
             }
         </style>
         <link rel="stylesheet" type="text/css" href="prettify/prettify.css" />
+        <script type="text/javascript" src="../../commondata.js"></script>
+        <script type="text/javascript" src="index.js"></script>
     </head>
     <body>
         <div id="header">
             <h1><a href="index.html">Документация Apache <strong>Cordova</strong></a></h1>
             <small>
-                <select></select>
+                <select id="language"></select>
+                <select id="version"></select>
+                <script>
+                setupLanguageSelect(); setupVersionSelect();
+                </script>
             </small>
         </div>
         <div id="subheader">
@@ -59,7 +65,6 @@
         </div>
 
         <!-- Functionality and Syntax Highlighting -->
-        <script type="text/javascript" src="index.js"></script>
         <script type="text/javascript" src="prettify/prettify.js"></script>
     </body>
 </html>


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org


Mime
View raw message