docs(website): Api docs navigation sidebar

serenity-js · Jul 5, 2019 · 01f2831 · 01f2831
1 parent 0bb8136
commit 01f2831
Show file tree

Hide file tree

Showing 14 changed files with 136 additions and 43 deletions.
diff --git a/.esdoc-patches.js b/.esdoc-patches.js
@@ -1,5 +1,7 @@
 const
     assert = require('assert'),
+    path   = require('path'),
+    fs     = require('fs'),
     AbstractDoc = require('esdoc/out/src/Doc/AbstractDoc').default;
 
 // --- Monkey patches
@@ -166,3 +168,22 @@ require('esdoc-publish-html-plugin/out/src/Builder/DocResolver').default.prototy
 
     this._data.__RESOLVED_LINK__ = true;
 };
+
+const _exec = require('esdoc-publish-html-plugin/out/src/Plugin')._exec.bind(require('esdoc-publish-html-plugin/out/src/Plugin'));
+require('esdoc-publish-html-plugin/out/src/Plugin')._exec = function patched_exec(tags, writeFile, copyDir, readFile) {
+
+    /**
+     * write .hbs instead of html so that they can be processed with MetalSmith
+     */
+    function patched_writeFile(filePath, content, option) {
+        const
+            [ext, ...parts] = filePath.split('.').reverse(),
+            fileName = parts.reverse().join('.');
+
+        const newFilePath = (ext === 'html') ? `${fileName}.html.hbs` : filePath;
+
+        return writeFile(newFilePath, content, option);
+    }
+
+    return _exec(tags, patched_writeFile, copyDir, readFile);
+};
diff --git a/documentation/esdoc-template/src/layout.html b/documentation/esdoc-template/src/layout.html
@@ -1,19 +1,29 @@
 <section>
-  <div class="container">
+  <main class="container">
     <div class="row">
-      <div class="col-lg-3 d-none d-lg-block">
-
+      <aside id="sidebar" class="col-lg-3 col-md-12">
         <nav class="toc navigation text-truncate" data-ice="nav">
-          <h3><a href="index.html">Readme</a></h3>
-          <h3><a href="identifiers.html">API Reference</a></h3>
-          <h3><a href="source.html">Source</a></h3>
-          <h3><a href="test.html" data-ice="testLink">Tests</a></h3>
+          <ul>
+            <li><a href="/modules">Modules</a></li>
+            <ul>
+            {{#each modules}}
+            <li><a href="{{ href }}" title="{{ description }}" class="{{#if (eq name ../module.name)}}active{{/if}}">{{ name }}</a></li>
+            {{/each}}
+            </ul>
+          </ul>
+          <hr />
+          <ul>
+            <li></li><a href="index.html">Readme</a></li>
+            <li></li><a href="source.html">Source code</a></li>
+            <li></li><a href="test.html" data-ice="testLink">Specs</a></li>
+            <li></li><a href="identifiers.html">API Reference</a></li>
+          </ul>
         </nav>
-      </div>
+      </aside>
 
-      <div class="col-lg-9 col-md-12">
-        <div class="content" data-ice="content"></div>
-      </div>
+      <section class="col-lg-9 col-md-12">
+        <article class="content" data-ice="content"></article>
+      </section>
     </div>
-  </div>
+  </main>
 </section>
diff --git a/documentation/esdoc-template/src/test.html b/documentation/esdoc-template/src/test.html
@@ -1,4 +1,4 @@
-<h1>Test</h1>
+<h1>Executable Specifications</h1>
 <table class="test-summary">
   <thead>
     <tr>

diff --git a/documentation/website/build.js b/documentation/website/build.js
@@ -46,7 +46,8 @@ Metalsmith(__dirname)
     .use(discoverModules('./node_modules/@serenity-js/*/package.json'))
     .use(fileMetadata([
         {pattern: '*.md', metadata: { 'layout': 'single-page-markdown.hbs' }},
-        {pattern: 'modules/**/*.html', metadata: { 'layout': 'api-docs.hbs' }},
+        {pattern: 'modules/**/*.hbs', metadata: { 'layout': 'api-docs.hbs' }},
+        {pattern: 'modules/index.hbs', metadata: { 'layout': 'default.hbs' }},
     ]))
     .use(inplace({
         rename: true,
@@ -68,7 +69,7 @@ Metalsmith(__dirname)
     .use(sass({
         outputStyle: 'expanded',
     }))
-    .use(debug(false))
+    // .use(debug(true))
     .use(browserSync({
         server: 'target/site',
         files: [

diff --git a/documentation/website/helpers/eq.js b/documentation/website/helpers/eq.js
@@ -0,0 +1,3 @@
+module.exports = function eq(left, right) {
+    return left === right;
+};
diff --git a/documentation/website/layouts/api-docs.hbs b/documentation/website/layouts/api-docs.hbs
@@ -12,7 +12,7 @@
     </div>
 </div>
 
-<section id="api-docs" class="block block-bb">
+<section id="api-docs">
 {{{ contents }}}
 </section>
 

diff --git a/documentation/website/layouts/handbook.hbs b/documentation/website/layouts/handbook.hbs
@@ -12,7 +12,7 @@
     </div>
 </div>
 
-<section id="handbook" class="block block-bb">
+<section id="handbook">
     <section>
         <div class="container">
             <div class="row">

diff --git a/documentation/website/layouts/single-page-markdown.hbs b/documentation/website/layouts/single-page-markdown.hbs
@@ -12,7 +12,7 @@
     </div>
 </div>
 
-<section id="handbook" class="block block-bb">
+<section id="handbook">
     <section>
         <div class="container">
             <div class="row">

diff --git a/documentation/website/plugins/debug.js b/documentation/website/plugins/debug.js
@@ -1,3 +1,5 @@
+const { inspect } = require('util');
+
 module.exports = function debug(logToConsole) {
     return function(files, metalsmith, done) {
         setImmediate(done);
@@ -8,10 +10,10 @@ module.exports = function debug(logToConsole) {
 
             // console.log(files);
 
-            // for (const f in files) {
-            //     console.log('\nFILE:');
-            //     console.log(files[f]);
-            // }
+            for (const f in files) {
+                console.log(`\nFILE: ${ f }`);
+                console.log(inspect(files[f]));
+            }
         }
     };
 };
diff --git a/documentation/website/plugins/discoverModules.js b/documentation/website/plugins/discoverModules.js
@@ -19,8 +19,22 @@ module.exports = function discoverSerenityJSModules(pattern) {
         });
     }
 
+    function moduleFor(pathToFile, discoveredModules) {
+        const moduleNameMatcher = /modules\/(.*?)\//;
+
+        if (! moduleNameMatcher.test(pathToFile)) {
+            // the file does not belong to any module (css files fall into this category)
+            return undefined;
+        }
+
+        const [ , moduleName ] = pathToFile.match(moduleNameMatcher);
+
+        return discoveredModules.find(module => module.shortName === moduleName);
+    }
+
     return function(files, ms, done) {
 
+        // build global metadata of all discovered modules
         glob(pattern, (err, matchedPackageJsonFiles) => {
             if (!! err) {
                 return done(err);
@@ -43,7 +57,16 @@ module.exports = function discoverSerenityJSModules(pattern) {
                     if (! metadata.modules.find(m => m.name === descriptor.name)) {
                         metadata.modules.push(descriptor);
                     }
-                })).then(() => done(), e => done(e));
+
+                    return descriptor;
+                }))
+                .then(moduleDescriptors => {
+                    // make every file "aware" of what module they belong to
+                    for (const f in files) {
+                        files[f].module = moduleFor(f, moduleDescriptors);
+                    }
+                })
+                .then(() => done(), e => done(e));
         });
     };
 };
diff --git a/documentation/website/src/css/api-docs/style.scss b/documentation/website/src/css/api-docs/style.scss
@@ -15,11 +15,6 @@
       border: none;
       margin-top: 0px;
     }
-
-    div {
-      border-top: 1px solid #ddd;
-      padding-top: 12px;
-    }
   }
 
   ul, ol {
@@ -156,19 +151,29 @@
   /*border-right: 1px solid #ddd;*/
   /*}*/
 
-  .navigation ul {
-    padding: 0;
-  }
+  .navigation {
+    ul {
+      padding: 0;
 
-  .navigation li {
-    list-style: none;
-    margin: 4px 0;
-    white-space: nowrap;
-  }
+      ul {
+        padding-left: 0.75em;
+      }
+    }
 
-  .navigation li a {
-    color: #666;
-    border: none;
+    li {
+      list-style: none;
+      margin: 4px 0;
+      white-space: nowrap;
+    }
+
+    a {
+      color: #666;
+      border: none;
+    }
+
+    a.active {
+      color: #000;
+    }
   }
 
   .navigation .nav-dir-path {
@@ -557,4 +562,4 @@
   .inner-link-active a {
     color: inherit;
   }
-}
+}
diff --git a/documentation/website/src/css/style.scss b/documentation/website/src/css/style.scss
@@ -44,6 +44,35 @@ a.anchorjs-link:hover {
   text-decoration: none;
 }
 
+#sidebar {
+  @media screen and (max-width: 992px) {
+    background-color: #FFFDF9;
+    border-bottom: 1px solid #F8E7CF;
+  }
+
+  @media screen and (min-width: 992px) {
+    &::before {
+      position: absolute;
+      top: 0;
+      right: 0;
+      bottom: 0;
+      left: -100vw;
+      content: "";
+      display: block;
+      background-color: #FFFDF9;
+      z-index: -1;
+    }
+
+    border-right: 1px solid #F8E7CF;
+  }
+
+  padding: 0.75em 1.5em 2.25em;
+}
+
+.content {
+  padding: 1.5em;
+}
+
 #handbook {
   nav.toc {
     ul {

diff --git a/documentation/website/src/modules/index.hbs b/documentation/website/src/modules/index.hbs
@@ -1,6 +1,5 @@
 ---
 title: Serenity/JS modules
-layout: default.hbs
 ---
 <section class="block block-bb">
     <div class="container">
@@ -32,4 +31,4 @@ layout: default.hbs
         </div>
         {{/inGroupsOf}}
     </div>
-</section>
+</section>
diff --git a/packages/core/src/io/formatted.ts b/packages/core/src/io/formatted.ts
@@ -3,7 +3,7 @@ import { inspected } from './inspected';
 
 /**
  * @desc
- *  A tag function returning a human-readable description of a template containing one or more {Answerable}s.
+ *  A tag function returning a human-readable description of a template containing one or more {@link Answerable}s.
  *
  * @link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
  *