You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by db...@apache.org on 2016/01/16 07:12:19 UTC
docs commit: Added new IA for English dev docs. Made paths in ToC
files relative (i.e. removed the redundant /docs/[lang]/[version]). Made docs
template support new ToC changes.
Repository: cordova-docs
Updated Branches:
refs/heads/nested-toc [created] 7658a75e7
Added new IA for English dev docs. Made paths in ToC files relative (i.e. removed the redundant /docs/[lang]/[version]). Made docs template support new ToC changes.
Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/7658a75e
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/7658a75e
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/7658a75e
Branch: refs/heads/nested-toc
Commit: 7658a75e7782d734abc58f16fc147c95b6cce690
Parents: 59827c2
Author: Dmitry Blotsky <dm...@gmail.com>
Authored: Fri Jan 15 22:11:54 2016 -0800
Committer: Dmitry Blotsky <dm...@gmail.com>
Committed: Fri Jan 15 22:11:54 2016 -0800
----------------------------------------------------------------------
tools/bin/toc.js | 38 ++++++++---
www/_data/toc/en-dev-manual.yml | 95 ++++++++++++++++++++------
www/_includes/toc_recursive_dropdown.html | 12 ++++
www/_includes/toc_recursive_main.html | 22 ++++++
www/_layouts/docs.html | 42 +++---------
www/static/css-src/_docs.scss | 34 +++++----
6 files changed, 166 insertions(+), 77 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/tools/bin/toc.js
----------------------------------------------------------------------
diff --git a/tools/bin/toc.js b/tools/bin/toc.js
index c09542c..f20e6cc 100644
--- a/tools/bin/toc.js
+++ b/tools/bin/toc.js
@@ -47,22 +47,36 @@ function getPageTitle(filePath) {
return null;
}
-function generate(sourceDir, prefix) {
+function generateToC(sourceDir) {
var deferred = Q.defer();
var toc = [];
+ // go through each file in sourceDir
var walker = walk.walk(sourceDir);
+ walker.on("file", function (dirPrefix, fileStats, next) {
- walker.on("file", function (root, fileStats, next) {
- var dirPrefix = root.replace(sourceDir, '');
- var filePath = path.join(dirPrefix, fileStats.name);
- var heading = getPageTitle(path.join(root, fileStats.name));
+ var fileName = fileStats.name;
+ var filePath = path.join(dirPrefix, fileName);
- if(heading) {
+ // get the page path
+ var pagePrefix = dirPrefix.replace(sourceDir, '');
+ var pagePath = path.join(pagePrefix, fileName);
+ var pageURI = pagePath.replace(".md", ".html").replace(/\\/g, "/");
+
+ // remove leading slash
+ if (pageURI[0] === "/") {
+ pageURI = pageURI.substr(1);
+ }
+
+ // get heading
+ var heading = getPageTitle(filePath);
+
+ // if the page has a heading, add it to the ToC
+ if (heading) {
toc.push({
- url: path.join(prefix, filePath).replace(".md", ".html").replace(/\\/g, "/"),
- name: heading
+ name: heading,
+ url: pageURI
});
}
@@ -105,16 +119,18 @@ function main () {
util.listdirsSync(languagePath).forEach(function (versionName) {
var versionPath = path.join(languagePath, versionName);
- var prefix = "/docs/" + languageName + "/" + versionName;
var outputName = util.generatedTocfileName(languageName, versionName);
var outputPath = path.join(tocRoot, outputName);
- // generate file
- generate(versionPath, prefix).then(function (toc) {
+ // generate ToC
+ generateToC(versionPath).then(function (toc) {
+
+ // sort the ToC
toc.sort(function (a, b) {
return a.name.localeCompare(b.name, languageName);
});
+ // save it to a file
var tocText = yaml.dump(toc);
console.log(outputPath);
fs.writeFileSync(outputPath, tocText, 'utf8');
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/www/_data/toc/en-dev-manual.yml
----------------------------------------------------------------------
diff --git a/www/_data/toc/en-dev-manual.yml b/www/_data/toc/en-dev-manual.yml
index 9fae782..cb1f8c3 100644
--- a/www/_data/toc/en-dev-manual.yml
+++ b/www/_data/toc/en-dev-manual.yml
@@ -1,21 +1,74 @@
-- {name: !!python/unicode 'Guides', url: !!python/unicode '/docs/en/dev/'}
-- {name: !!python/unicode 'Overview', url: !!python/unicode '/docs/en/dev/guide/overview/index.html'}
-- {name: !!python/unicode 'Platform Support', url: !!python/unicode '/docs/en/dev/guide/support/index.html'}
-- {name: !!python/unicode 'The Command-Line Interface', url: !!python/unicode '/docs/en/dev/guide/cli/index.html'}
-- {name: !!python/unicode 'Platform Guides', url: !!python/unicode '/docs/en/dev/guide/platforms/index.html'}
-- {name: !!python/unicode 'Using Plugman to Manage Plugins', url: !!python/unicode '/docs/en/dev/plugin_ref/plugman.html'}
-- {name: !!python/unicode 'The config.xml File', url: !!python/unicode '/docs/en/dev/config_ref/index.html'}
-- {name: !!python/unicode 'Icons and Splash Screens', url: !!python/unicode '/docs/en/dev/config_ref/images.html'}
-- {name: !!python/unicode 'Embedding WebViews', url: !!python/unicode '/docs/en/dev/guide/hybrid/webviews/index.html'}
-- {name: !!python/unicode 'Plugin Development Guide', url: !!python/unicode '/docs/en/dev/guide/hybrid/plugins/index.html'}
-- {name: !!python/unicode 'Plugin Specification', url: !!python/unicode '/docs/en/dev/plugin_ref/spec.html'}
-- {name: !!python/unicode 'Privacy Guide', url: !!python/unicode '/docs/en/dev/guide/appdev/privacy/index.html'}
-- {name: !!python/unicode 'Security Guide', url: !!python/unicode '/docs/en/dev/guide/appdev/security/index.html'}
-- {name: !!python/unicode 'Platforms and Plugins Version Management', url: !!python/unicode '/docs/en/dev/platform_plugin_versioning_ref/index.html'}
-- {name: !!python/unicode 'Whitelist Guide', url: !!python/unicode '/docs/en/dev/guide/appdev/whitelist/index.html'}
-- {name: !!python/unicode 'Storage', url: !!python/unicode '/docs/en/dev/cordova/storage/storage.html'}
-- {name: !!python/unicode 'Hooks Guide', url: !!python/unicode '/docs/en/dev/guide/appdev/hooks/index.html'}
-- {name: !!python/unicode 'Next Steps', url: !!python/unicode '/docs/en/dev/guide/next/index.html'}
-- {name: !!python/unicode 'Events', url: !!python/unicode '/docs/en/dev/cordova/events/events.html'}
-- {name: !!python/unicode 'Plugin APIs', url: !!python/unicode '/docs/en/dev/cordova/plugins/pluginapis.html'}
-- {name: !!python/unicode 'Keyword Index', url: !!python/unicode '/docs/en/dev/page_index.html'}
+- name: Overview
+ url: 'guide/overview/index.html'
+- name: Architecture
+ url:
+ children:
+ - name: Runtime Architecture
+ url:
+ - name: Tooling Architecture
+ url:
+- name: Create apps
+ url:
+ children:
+ - name: Create your first app
+ url:
+ - name: Develop for platforms
+ url: 'guide/platforms/index.html'
+ - name: Manage versions and platforms
+ url:
+ - name: Debug and test
+ url:
+ - name: Automate Tasks
+ url:
+ - name: Store data
+ url:
+ - name: Manage privacy
+ url:
+ - name: Manage security
+ url:
+ - name: Whitelisting
+ url:
+ - name: Publish
+ url:
+- name: Create plugins
+ url: 'guide/hybrid/plugins/index.html'
+ children:
+ - name: Create a plugin
+ url:
+ - name: Register with NPM
+ url:
+ - name: Develop for platforms
+ url:
+ - name: Use Plugman
+ url:
+ - name: Debug and test
+ url:
+- name: Advanced Topics
+ url:
+ children:
+ - name: Embed Cordova in native apps
+ url:
+ - name: Pass data from Cordova app to host
+ url:
+- name: Reference
+ url:
+ children:
+ - name: Config.xml
+ url:
+ - name: Events
+ url:
+ - name: Plugin APIs
+ url:
+ - name: CLI
+ url:
+ - name: Hooks
+ url:
+ - name: Plugin.xml
+ url:
+- name: Tutorials
+ url:
+ children:
+ - name: Share your app in source control
+ url:
+- name: Sample Apps
+ url:
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/www/_includes/toc_recursive_dropdown.html
----------------------------------------------------------------------
diff --git a/www/_includes/toc_recursive_dropdown.html b/www/_includes/toc_recursive_dropdown.html
new file mode 100644
index 0000000..f78ea8f
--- /dev/null
+++ b/www/_includes/toc_recursive_dropdown.html
@@ -0,0 +1,12 @@
+{% for entry in include.entries %}
+{% if entry.url != null %}
+<li>
+ <a class="{% if include.my_entry == entry.url %}this-page{% endif %}" href="{{ include.path_to_root }}{{ entry.url }}">
+ {{ entry.name }}
+ </a>
+</li>
+{% endif %}
+{% if entry.children %}
+{% include toc_recursive_dropdown.html entries=entry.children my_entry=include.my_entry path_to_root=include.path_to_root %}
+{% endif %}
+{% endfor %}
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/www/_includes/toc_recursive_main.html
----------------------------------------------------------------------
diff --git a/www/_includes/toc_recursive_main.html b/www/_includes/toc_recursive_main.html
new file mode 100644
index 0000000..3e8295b
--- /dev/null
+++ b/www/_includes/toc_recursive_main.html
@@ -0,0 +1,22 @@
+<ul class="site-toc">
+ {% for entry in include.entries %}
+ <li>
+ {% if entry.url != null %}
+ <a class="{% if include.my_entry == entry.url %}this-page{% endif %}" href="{{ include.path_to_root }}{{ entry.url }}">
+ {{ entry.name }}
+ </a>
+ {% else %}
+ {{ entry.name }}
+ {% endif %}
+
+ {% comment %}
+ Insert page-specific ToC here if this is the entry for this page
+ {% endcomment %}
+ {% if include.my_entry == entry.url %}<div id="page-toc" class="page-toc"></div>{% endif %}
+
+ {% if entry.children %}
+ {% include toc_recursive_main.html entries=entry.children my_entry=include.my_entry path_to_root=include.path_to_root %}
+ {% endif %}
+ </li>
+ {% endfor %}
+</ul>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/www/_layouts/docs.html
----------------------------------------------------------------------
diff --git a/www/_layouts/docs.html b/www/_layouts/docs.html
index ad98d92..25291b0 100644
--- a/www/_layouts/docs.html
+++ b/www/_layouts/docs.html
@@ -12,33 +12,24 @@ analytics_id: UA-64283057-1
{% assign tocfile = toc_dir.[page.generated_toc] %}
{% endif %}
+{% capture version_prefix %}/docs/{{ page.language }}/{{ page.version }}/{% endcapture %}
+{% assign my_entry = page.url | replace: version_prefix,"" %}
+{% assign my_entry_parts = my_entry | split: "/" %}
+
{% comment %}
- <!-- We want TOC links to be relative in order to make sure we preserve aliases
- like "latest" in the URL. The captures are both horrendous single line
- statements in order to prevent the capturing of extra whitespace. -->
-{% endcomment %}
+ path_to_root: path from here to version root, replacing all parts except the last one with '../'
-{% assign url_split = page.url | split: "/" %}
-{% capture relative_base_path %}{% for item in url_split %}{% if forloop.index0 > 3 and forloop.rindex > 1 %}../{% endif %}{% endfor %}{% endcapture %}
-{% capture actual_base_path %}{% for item in url_split %}{% if forloop.index0 < 4 and forloop.index0 != 0 %}/{{item}}{% endif %}{% endfor %}/{% endcapture %}
+ NOTE:
+ the capture is a single line because extraneous whitespace would screw up the URI it produces
+{% endcomment %}
+{% capture path_to_root %}{% for item in my_entry_parts %}{% if forloop.rindex > 1 %}../{% endif %}{% endfor %}{% endcapture %}
<div class="docs container">
<!-- Table of Contents -->
<div class="hidden-xs hidden-sm col-md-3 site-toc-container">
<h2 class="site-toc-title">{{ page.toc_text }}</h2>
- <ul class="site-toc">
- {% for entry in tocfile %}
- <li>
- <a class="{% if page.url == entry.url %}this-page{% endif %}" href="{{ entry.url | replace:actual_base_path,relative_base_path }}">
- {{ entry.name }}
- </a>
- {% if page.url == entry.url %}
- <div id="page-toc" class="page-toc"></div>
- {% endif %}
- </li>
- {% endfor %}
- </ul>
+ {% include toc_recursive_main.html entries=tocfile my_entry=my_entry path_to_root=path_to_root %}
</div>
<!-- Page content -->
@@ -52,18 +43,7 @@ analytics_id: UA-64283057-1
<span class="caret"></span>
</button>
<ul class="dropdown-menu">
- {% for entry in tocfile %}
- <li>
- <a class="{% if page.url == entry.url %}this-page{% endif %}" href="{{ entry.url | replace:actual_base_path,relative_base_path }}">
- {% if page.url == entry.url %}
- <em>{{ entry.name }}</em>
- {% else %}
- {{ entry.name }}
- <!-- DEBUG: {{ page.url }} != {{ entry.url }} -->
- {% endif %}
- </a>
- </li>
- {% endfor %}
+ {% include toc_recursive_dropdown.html entries=tocfile my_entry=my_entry path_to_root=path_to_root %}
</ul>
</div>
</div>
http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/7658a75e/www/static/css-src/_docs.scss
----------------------------------------------------------------------
diff --git a/www/static/css-src/_docs.scss b/www/static/css-src/_docs.scss
index 2f83d8d..03e9994 100644
--- a/www/static/css-src/_docs.scss
+++ b/www/static/css-src/_docs.scss
@@ -1,6 +1,10 @@
.docs {
margin-bottom: 20px;
+ .this-page {
+ font-weight: bold;
+ }
+
/* this is so that wide images don't stick out of their paragraphs */
p {
img {
@@ -24,20 +28,22 @@
}
/* outer ToC for the site */
- .site-toc {
- padding: 0px;
- }
- .site-toc li {
- list-style: none;
- }
- .site-toc > li {
- list-style: none;
- font-size: 18px;
- font-weight: 300;
- padding: 0.5em 0em;
- }
- .site-toc > li .this-page {
- font-weight: bold;
+ .site-toc-container {
+ .site-toc {
+ padding: 0px;
+ .site-toc {
+ padding-left: 15px;
+ }
+ }
+ .site-toc li {
+ list-style: none;
+ }
+ .site-toc > li {
+ list-style: none;
+ font-size: 18px;
+ font-weight: 300;
+ padding-top: 0.5em;
+ }
}
/* inner ToC for the page */
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org