feat(manual): card index for manual

esdoc.json

@@ -23,6 +23,7 @@
   ],
   "manual": {
     "asset": "./manual/asset",
+    "index": "./manual/index.md",
     "overview": ["./manual/overview.md", "./manual/feature.md"],
     "design": ["./manual/design.md"],
     "installation": ["./manual/installation.md"],

manual/index.md

@@ -0,0 +1,2 @@
+# ESDoc Manual
+tbd

src/ESDoc.js

@@ -174,6 +174,10 @@ export default class ESDoc {
       if (!config.test.includes) config.test.includes = ['(spec|Spec|test|Test)\\.(js|es6)$'];
       if (!config.test.excludes) config.test.excludes = ['\\.config\\.(js|es6)$'];
     }
+
+    if (config.manual) {
+      if (!('coverage' in config.manual)) config.manual.coverage = true;
+    }
   }
 
   /* eslint-disable no-unused-vars */

src/Publisher/Builder/ManualDocBuilder.js

@@ -27,11 +27,13 @@ export default class ManualDocBuilder extends DocBuilder {
       const fileName = 'manual/index.html';
       const baseUrl = this._getBaseUrl(fileName);
       this._buildManualIndex(manualConfig);
-      ice.load('content', this._buildManualIndex(manualConfig, true), IceCap.MODE_WRITE);
+      ice.load('content', this._buildManualCardIndex(manualConfig), IceCap.MODE_WRITE);
       ice.load('nav', this._buildManualNav(manualConfig), IceCap.MODE_WRITE);
       ice.text('title', 'Manual', IceCap.MODE_WRITE);
       ice.attr('baseUrl', 'href', baseUrl, IceCap.MODE_WRITE);
+      ice.attr('rootContainer', 'class', ' manual-index');
       callback(ice.html, fileName);
+      ice.attr('rootContainer', 'class', ' manual-index', IceCap.MODE_REMOVE);
     }
 
     for (const item of manualConfig) {
@@ -144,18 +146,77 @@ export default class ManualDocBuilder extends DocBuilder {
     return $root.html();
   }
 
+  /**
+   * built manual card style index.
+   * @param {ManualConfigItem[]} manualConfig - target manual config.
+   * @return {IceCap} built index.
+   * @private
+   */
+  _buildManualCardIndex(manualConfig) {
+    const cards = [];
+    for (const manualItem of manualConfig) {
+      if (manualItem.references) {
+        const filePath = path.resolve(this._config.destination, 'identifiers.html');
+        const html = fs.readFileSync(filePath).toString();
+        const $ = cheerio.load(html);
+        const card = $('.content').html();
+        cards.push({label: 'References', link: 'identifiers.html', card: card});
+        continue;
+      }
+
+      for (const filePath of manualItem.paths) {
+        const fileName = this._getManualOutputFileName(manualItem, filePath);
+        const html = this._buildManual(manualItem, filePath);
+        const $root = cheerio.load(html).root();
+
+        $root.find('h1').each((i, el)=>{
+          const $el = cheerio(el);
+          const label = $el.text();
+          const link = `${fileName}#${$el.attr('id')}`;
+          let card = `<h1>${label}</h1>`;
+          const nextAll = $el.nextAll();
+
+          for (let i = 0 ; i < nextAll.length; i++) {
+            const next = nextAll.get(i);
+            const tagName = next.tagName.toLowerCase();
+            if (tagName === 'h1') return;
+            const $next = cheerio(next);
+            card += `<${tagName}>${$next.html()}</${tagName}>`;
+          }
+
+          cards.push({label, link, card});
+        });
+      }
+    }
+
+    const ice = new IceCap(this._readTemplate('manualCardIndex.html'));
+    ice.loop('cards', cards, (i, card, ice)=>{
+      ice.text('label', card.label) ;
+      ice.attr('link', 'href', card.link);
+      ice.load('card', card.card);
+    });
+
+    if (this._config.manual.index) {
+      const userIndex = this._convertMDToHTML(this._config.manual.index);
+      ice.load('manualUserIndex', userIndex);
+    } else {
+      ice.drop('manualUserIndex', true);
+    }
+
+    ice.drop('manualBadge', !this._config.manual.coverage);
+
+    return ice;
+  }
+
   /**
    * built manual index.
    * @param {ManualConfigItem[]} manualConfig - target manual config.
-   * @param {boolean} [badge=false] - show badge.
    * @return {IceCap} built index.
    * @private
    */
-  _buildManualIndex(manualConfig, badge = false) {
+  _buildManualIndex(manualConfig) {
     const ice = new IceCap(this._readTemplate('manualIndex.html'));
 
-    if (!badge) ice.drop('badge');
-
     ice.loop('manual', manualConfig, (i, item, ice)=>{
       const toc = [];
       if (item.references) {

src/Publisher/Builder/template/css/style.css

@@ -12,7 +12,8 @@ html
   overflow: auto;
   font-size: 14px;
   /*color: #4d4e53;*/
-  color: rgba(0, 0, 0, .68);
+  /*color: rgba(0, 0, 0, .68);*/
+  color: #444;
   background-color: #fff;
 }
 
@@ -124,10 +125,12 @@ li > code {
   z-index: 1;
   background-color: white;
   top: 0;
-  border-bottom: solid 1px #E02130;
+  border-bottom: solid 1px #ddd;
+  box-shadow: #ddd 1px 1px 1px;
 }
 .layout-container > header > a{
   margin: 0 5px;
+  color: #444;
 }
 
 .layout-container > header > a.repo-url-github {
@@ -153,7 +156,7 @@ li > code {
   margin-top:1em;
   overflow-x: scroll;
   box-shadow: rgba(255, 255, 255, 1) -1px 0 0 inset;
-  border-right: 1px solid rgba(0, 0, 0, 0.1);
+  border-right: 1px solid #ddd;
 }
 
 .navigation ul {
@@ -746,16 +749,71 @@ table.test-summary .test-target > span:first-child {
 
 /** manual */
 
+.manual-index .manual-cards {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.manual-index .manual-card-wrap {
+  width: 33%;
+  padding: 10px 20px 10px 0;
+  box-sizing: border-box;
+}
+
+.manual-index .manual-card-wrap > h1 {
+  border: none;
+  margin: 0;
+  font-size: 1.5em;
+}
+
+.manual-index .manual-card {
+  height: 200px;
+  overflow: hidden;
+  border: solid 1px #ddd;
+  border-radius: 4px;
+  padding: 8px;
+  position: relative;
+}
+
+.manual-index .manual-card > div {
+  transform: scale(0.4);
+  transform-origin: 0 0;
+  width: 250%;
+}
+
+.manual-index .manual-card > a {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: rgba(210, 210, 210, 0.1);
+}
+
+.manual-index .manual-card > a:hover {
+  background: none;
+}
+
+.manual-index .manual-badge {
+  margin: 0;
+}
+
+.manual-index .manual-user-index {
+  margin-bottom: 1em;
+  border-bottom: solid 1px #ddd;
+}
+
 .manual-root .navigation {
-  padding-left: 0;
+  padding-left: 4px;
+  margin-top: 4px;
 }
 
 .navigation .manual-toc {
   margin-top: -0.25em;
 }
 
-.navigation .manual-toc li {
-  white-space: normal;
+.navigation .manual-toc-root > div {
+  padding-top: 1px;
 }
 
 .github-markdown .manual-toc-title a {
@@ -788,11 +846,13 @@ table.test-summary .test-target > span:first-child {
 }
 
 .navigation .manual-toc .indent-h1 {
-  background: #039BE5;
-  padding: 0.5em;
+  /*background: rgb(37, 138, 175);*/
+  /*padding: 0.5em;*/
+  margin: 1em 0 0 0.5em;
 }
 .navigation .manual-toc .indent-h1 a {
-  color: #fff;
+  color: #444;
+  font-weight: bold;
 }
 
 .manual-toc .indent-h1 {
@@ -897,6 +957,13 @@ table.test-summary .test-target > span:first-child {
   background-color: #f8f8f8;
 }
 
+.github-markdown hr {
+  border-right: 0;
+  border-bottom: 1px solid #e5e5e5;
+  border-left: 0;
+  border-top: 0;
+}
+
 /** badge(.svg) does not have border */
 .github-markdown img:not([src*=".svg"]) {
   max-width: 100%;

src/Publisher/Builder/template/manualCardIndex.html

@@ -0,0 +1,15 @@
+<div class="github-markdown">
+  <div class="manual-user-index" data-ice="manualUserIndex"></div>
+
+  <p class="manual-badge" data-ice="manualBadge"><img src="./manual-badge.svg"/></p>
+
+  <div class="manual-cards">
+    <div class="manual-card-wrap" data-ice="cards">
+      <h1 data-ice="label"></h1>
+      <div class="manual-card">
+        <div data-ice="card"></div>
+        <a data-ice="link"></a>
+      </div>
+    </div>
+  </div>
+</div>

src/Publisher/Builder/template/manualIndex.html

@@ -1,5 +1,4 @@
 <div class="github-markdown manual-toc-root">
-  <img src="./manual-badge.svg" data-ice="badge"/>
   <div data-ice="manual">
     <ul class="manual-toc">
       <li data-ice="manualNav"><a href="" data-ice="link"></a></li>

test/fixture/package/esdoc.json

@@ -12,6 +12,7 @@
     "includes": ["Test.js$"]
   },
   "manual": {
+    "index": "./test/fixture/package/manual/index.md",
     "overview": ["./test/fixture/package/manual/overview.md"],
     "design": ["./test/fixture/package/manual/design.md"],
     "installation": ["./test/fixture/package/manual/installation.md"],

test/fixture/package/manual/index.md

@@ -0,0 +1,2 @@
+# ESDoc Manual
+tbd