# This is a combination of 27 commits.

# This is the 1st commit message:

Adding start of Workbox v3 alpha docs

# This is the commit message #2:

Adding v3 alpha

# This is the commit message #3:

Adding configuration guide

# This is the commit message #4:

Adding workbox-precaching and fixing nested parameters

# This is the commit message #5:

Setting up namespaced docs on WF

# This is the commit message #6:

Adding ref and module docs for precaching

# This is the commit message #7:

Adding ref and module docs for precaching

# This is the commit message #8:

Routing Docs and module guide

# This is the commit message #9:

Routing Docs and module guide

# This is the commit message #10:

Adding workbox-cache-expiration guide and reference docs

# This is the commit message #11:

Adding routing docs

# This is the commit message #12:

Changing menu name

# This is the commit message #13:

Adding ability to use custom project yaml

# This is the commit message #14:

Adding workbox pages

# This is the commit message #15:

Getting it to work on devsite staging

# This is the commit message #16:

Adding some headings instead of sections but need to stage

# This is the commit message #17:

Moving to heading

# This is the commit message #18:

Adding heading support for navigation

# This is the commit message #19:

Adding contributor list

# This is the commit message #20:

Adding more content for docs

# This is the commit message #21:

Adding in company logos

# This is the commit message #22:

Adding in company logos

# This is the commit message #23:

Adding logos

# This is the commit message #24:

Adding some fixes for left nav

# This is the commit message #25:

Renaming strategies

# This is the commit message #26:

Fixng ref doc bug and add missing module pages

# This is the commit message #27:

Adding Guides etc

devsiteHelper.py

@@ -152,7 +152,7 @@ def parseBookYaml(pathToBook, lang='en'):
       upperTabs.append(expandBook(upperTab))
     return result
   except Exception as e:
-    logging.exception('Error in parseBookYaml')
+    logging.exception(e)
   return None
 
 
@@ -199,9 +199,12 @@ def getLowerTabs(bookYaml):
         for lowerTab in tab['lower_tabs']['other']:
           lt = {}
           lt['name'] = lowerTab['name']
-          if 'contents' in lowerTab and 'path' in lowerTab['contents'][0]:
-            lt['path'] = lowerTab['contents'][0]['path']
-            result.append(lt)
+          if 'contents' in lowerTab:
+            for lowerTabContent in lowerTab['contents']:
+             if 'path' in lowerTabContent:
+                lt['path'] = lowerTabContent['path']
+                result.append(lt)
+                break
   except Exception as e:
     logging.exception('Unable to read/parse the lower tabs')
   return result
@@ -220,15 +223,24 @@ def getLeftNav(requestPath, bookYaml, lang='en'):
     for upperTab in bookYaml['upper_tabs']:
       if 'path' in upperTab and requestPath.startswith(upperTab['path']):
         for lowerTab in upperTab['lower_tabs']['other']:
-          if ('path' not in lowerTab['contents'][0] or
-            requestPath.startswith(lowerTab['contents'][0]['path'])):
+          firstPathInLowerTab = None
+          for lowerTabContent in lowerTab['contents']:
+             if 'path' in lowerTabContent:
+                firstPathInLowerTab = lowerTabContent['path']
+                break
+          if (firstPathInLowerTab is None):
+            if 'path' in lowerTab:
+              firstPathInLowerTab = lowerTab['path']
+          if (firstPathInLowerTab is None or
+            requestPath.startswith(firstPathInLowerTab)):
               result = '<ul class="devsite-nav-list devsite-nav-expandable">\n'
               result += buildLeftNav(lowerTab['contents'])
               result += '</ul>\n'
     return result
   except Exception as e:
     msg = ' - Unable to read or parse primary book.yaml'
     logging.exception(msg)
+    logging.exception(e)
     whoops += '<p>Exception occured.</p>'
     return whoops
 
@@ -243,6 +255,13 @@ def buildLeftNav(bookYaml, lang='en'):
       result += '<span>' + cgi.escape(item['title']) + '</span>\n'
       result += '</a>\n'
       result += '</li>\n'
+    elif 'heading' in item:
+      result += '<li class="devsite-nav-item devsite-nav-item-heading">\n';
+      result += '<span class="devsite-nav-title devsite-nav-title-no-path" ';
+      result += 'track-type="leftNav" track-name="expandNavSectionNoLink" ';
+      result += 'track-metadata-position="0">\n';
+      result += '<span>' + cgi.escape(item['heading']) + '</span>\n';
+      result += '</span>\n</li>\n';
     elif 'section' in item:
       # Sub-section
       result += '<li class="devsite-nav-item devsite-nav-item-section-expandable">\n'

devsiteParseYAML.py

@@ -58,6 +58,8 @@ def parse(requestPath, fileLocation, rawYaml, lang='en'):
     if 'heading' in row:
       section += '<h2 id="' + devsiteHelper.slugify(row['heading']) +'">'
       section += row['heading'] + '</h2>'
+    if 'description' in row:
+      section += row['description']
     if 'items' in row:
       section += '<div class="devsite-landing-row-group">'
       section += parseIndexYamlItems(row['items'])

gulp-tasks/build.js

@@ -20,6 +20,10 @@ gulp.task('build:announcement', function() {
   const globOpts = {
     srcBase: 'src/content/en/',
     prefixBase: true,
+    ignore: [
+      // Disable forced announcements on Workbox.
+      '**/workbox/**/_project.yaml',
+    ]
   };
   const dumpYamlOpts = {lineWidth: 1000};
   const projectYamlFiles = glob.find('**/_project.yaml', globOpts);

gulp-tasks/workbox-v3-ref-docs.js

@@ -0,0 +1,194 @@
+const gulp = require('gulp');
+const remoteGitTags = require('remote-git-tags');
+const semver = require('semver');
+const fse = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const spawn = require('child_process').spawn;
+const glob = require('glob');
+
+const PREVIOUS_RELEASES = 0;
+
+const buildJSDocs = (srcCodePath, docOutputPath, jsdocConfPath) => {
+  console.log(`\n\n    Building JSDocs to '${path.relative(process.cwd(), docOutputPath)}'.`);
+
+  try {
+    fse.accessSync(jsdocConfPath, fse.F_OK);
+  } catch (err) {
+    console.warn(`Unable to find jsdoc Config File @ '${jsdocConfPath}'`);
+    console.warn(err);
+    return;
+  }
+
+  const contentPath = path.join(__dirname, '..', 'src', 'content', 'en');
+  const templateBasePath = path.join(
+    path.posix.sep,
+    'web',
+    path.relative(contentPath, docOutputPath)
+  );
+  console.log(`\n\n    Using JSDoc basepath=${templateBasePath}.`);
+
+  const jsdocConfigContents = fse.readFileSync(jsdocConfPath);
+  const jsdocConfig = JSON.parse(jsdocConfigContents);
+  if (!jsdocConfig.webFundamentals) {
+    console.warn(`In your JSDoc config file you MUST provide a 'webFundamentals' property with:`);
+    console.warn(`    projectRoot`);
+    console.warn(`    productName`);
+    return;
+  }
+
+  const queryString = [
+    `projectRoot=${jsdocConfig.webFundamentals.projectRoot}`,
+    `basepath=${templateBasePath}`,
+    `productName=${jsdocConfig.webFundamentals.productName}`,
+  ].join('&');
+
+  const jsDocParams = [
+    '--template', path.join(
+      __dirname, '..', 'src', 'templates', 'reference-docs', 'jsdoc'
+    ),
+    '-c', jsdocConfPath,
+    '-d', docOutputPath,
+    '--query', queryString,
+  ];
+
+  console.log(`    JSDoc Params: `, jsDocParams);
+
+  const jsdocPath = path.join(__dirname, '..', 'node_modules', 'jsdoc', 'jsdoc.js');
+
+  return new Promise((resolve, reject) => {
+    const jsdocProcess = spawn(jsdocPath, jsDocParams, {
+      cwd: srcCodePath,
+      stdio: 'inherit',
+    });
+
+    jsdocProcess.on('error', (err) => {
+      console.error('\n\nUnable to run jsdoc.');
+      console.error(err);
+    });
+
+    jsdocProcess.on('close', (code) => {
+      if (code === 0) {
+        resolve(docOutputPath);
+      } else {
+        reject(`Error code: ${code}`);
+      }
+    });
+  })
+  .then((docOutputPath) => {
+    // jsdoc-baseline copies over these files for it's own template
+    // but we don't use them for devsite - so remove these files.
+    fse.removeSync(path.join(docOutputPath, 'css'));
+    fse.removeSync(path.join(docOutputPath, 'scripts'));
+
+    return docOutputPath;
+  })
+  .then((docOutputPath) => {
+    // Web Fundamentals linting errors on developers.google.com
+    const allFiles = glob.sync(path.join(docOutputPath, '**', '*'), {
+      absolute: true,
+    });
+    allFiles.forEach((filePath) => {
+      const fileContents = fse.readFileSync(filePath).toString();
+      const cleanContents = fileContents
+        .split('https://developers.google.com/').join('/');
+      fse.writeFileSync(filePath, cleanContents);
+    });
+
+    return docOutputPath;
+  })
+  .catch((err) => {
+    // If we error'd, make sure we didn't create a directory that will stop
+    // future doc builds.
+    fse.removeSync(docOutputPath);
+
+    console.error(`\n\nUnable to build docs for: '${path.relative(process.cwd(), docOutputPath)}'`);
+    console.error(err);
+
+    return null;
+  });
+};
+
+const getSourceCode = (gitUrl, tag, tmpPath) => {
+  fse.ensureDirSync(tmpPath);
+
+  return new Promise((resolve, reject) => {
+    const gitDownload = spawn('git', [
+      'clone',
+      '--branch', tag,
+      '--depth', '1',
+      '--config', 'advice.detachedHead=false',
+      gitUrl,
+      tmpPath,
+    ], {
+      stdio: 'inherit',
+    });
+
+    gitDownload.on('error', (err) => {
+      console.error(`\n\nUnable to retrieve tag '${tag}' from Git.`);
+      console.error(err);
+      reject(`Unable to retrieve tag '${tag}' from Git.`);
+    });
+
+    gitDownload.on('close', (code) => {
+      if (code === 0) {
+        resolve(tmpPath);
+      } else {
+        reject(`Error ${code} returned by command: 'git ${params.join(' ')}'`);
+      }
+    });
+  });
+};
+
+const generateRefDocs = (projectName, gitUrl, docPath, tag, jsdocConfPath, isLatest) => {
+  // 1. Check if current tag exists, if so return
+  const outputPath = path.join(docPath, tag);
+  if (fse.pathExistsSync(outputPath)) {
+    return;
+  }
+
+  console.log(`\n\nNeed to build docs for '${projectName}: ${tag}'`);
+
+  const tmpDirectory = path.join(os.tmpdir(), Date.now().toString());
+  const tmpSrCodePath = path.join(tmpDirectory, tag);
+  return getSourceCode(gitUrl, tag, tmpSrCodePath)
+  .then(() => {
+    if (isLatest) {
+      const outputPath = path.join(docPath, 'latest');
+      return buildJSDocs(tmpSrCodePath, outputPath, jsdocConfPath);
+    }
+  })
+  .then(() => {
+    if (PREVIOUS_RELEASES > 0) {
+      return buildJSDocs(tmpSrCodePath, outputPath, jsdocConfPath);
+    }
+  })
+  .then(() => {
+    fse.removeSync(tmpDirectory);
+  }, (err) => {
+    fse.removeSync(tmpDirectory);
+    throw err;
+  });
+};
+
+const buildReferenceDocs = (projectName, gitUrl, localPath, jsdocConfPath) => {
+  fse.removeSync(path.join(localPath, 'latest'));
+
+  return generateRefDocs(
+    projectName,
+    gitUrl,
+    localPath,
+    'v3',
+    jsdocConfPath,
+    true,
+  );
+};
+
+gulp.task('reference-docs:workbox-v3', () => {
+  return buildReferenceDocs(
+    'Workbox',
+    'https://github.com/GoogleChrome/workbox.git',
+    path.join(__dirname, '..', 'src/content/en/tools/workbox/v3/reference-docs/'),
+    path.join(__dirname, '..', 'src/content/en/tools/workbox/v3/_jsdoc.conf')
+  );
+});

gulp-tasks/workbox:generate-contributors.js

@@ -0,0 +1,94 @@
+const GitHubApi = require('github');
+const fs = require('fs-extra');
+const path = require('path');
+const gulp = require('gulp');
+
+const MAX_COLLABORATORS = 20;
+
+function getContributorHTML(contributorStats) {
+  const contributor = contributorStats.author;
+  let html = `
+<div class="wb-contrib">
+  <a class="wb-contrib__img-link" href="${contributor.url}" target="_blank">
+    <img class="wb-contrib__image" src="${contributor.avatar_url}">
+  </a>
+  <br />
+  <a class="wb-contrib__link" href="${contributor.url}" target="_blank">
+    ${contributor.login}
+  </a>
+</div>
+`;
+  return html;
+}
+
+gulp.task(`workbox:generate-contributors`, function() {
+  if (!process.env.GITHUB_TOKEN) {
+    console.warn(`Unable to build Workbox contributors due to no ` +
+      `GITHUB_TOKEN existing on the current Path.`);
+
+    // Return a promise so gulp is happy and thinks the task completed
+    return Promise.resolve();
+  }
+
+  const github = new GitHubApi();
+  github.authenticate({
+    type: 'token',
+    token: process.env.GITHUB_TOKEN
+  });
+
+  return github.repos.getStatsContributors({
+    owner: 'googlechrome',
+    repo: 'workbox',
+  })
+  .then((contributorStats) => {
+    contributorStats.sort((a, b) => b.total - a.total);
+    if (contributorStats.length > MAX_COLLABORATORS) {
+      contributorStats = contributorStats.splice(0, MAX_COLLABORATORS);
+    }
+    return contributorStats.map(getContributorHTML).join('');
+  })
+  .then((html) => {
+    const finalHtml = `{% framebox height="auto" %}
+<!-- This file is auto-generated by 'gulp workbox:generate-contributors' -->
+<style>
+.workbox-contributors-container {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  justify-content: space-around;
+}
+
+.wb-contrib {
+  text-align: center;
+  margin: 10px;
+}
+
+.wb-contrib a {
+  color: inherit;
+}
+
+.wb-contrib__image {
+  width: 80px;
+  height: 80px;
+  border-radius: 100%;
+  box-shadow: 0 4px 6px #616161;
+
+  background-color: white;
+}
+</style>
+<div class="workbox-contributors-container">
+${html}
+</div>
+{% endframebox %}`;
+    const templatePath = path.join(__dirname, '..', 'src', 'content',
+      'en', 'tools', 'workbox', 'templates', 'contributors.html');
+    return fs.ensureDir(path.dirname(templatePath))
+    .then(() => fs.writeFile(templatePath, finalHtml))
+    .catch((err) => {
+      console.warn(`An error occured when generating the Workbox ` +
+        `collaborators.`);
+      console.warn(`This is not a vital error.`);
+      console.warn(err);
+    });
+  });
+});

src/content/en/tools/_book.yaml

@@ -22,8 +22,8 @@ upper_tabs:
       - name: Workbox
         contents:
         - include: /web/tools/workbox/_toc.yaml
-      - name: Chrome User Experience Report
-        contents:
-        - include: /web/tools/chrome-user-experience-report/_toc.yaml
+#      - name: Chrome User Experience Report
+#        contents:
+#        - include: /web/tools/chrome-user-experience-report/_toc.yaml
   - include: /web/_upper_tabs-Updates.yaml
   - include: /web/_upper_tabs-Showcase.yaml

src/content/en/tools/workbox/_toc.yaml

@@ -23,3 +23,5 @@ toc:
 - title: Github
   path: https://github.com/GoogleChrome/workbox
   status: external
+# - title: Next Release (Alpha)
+#   path: /web/tools/workbox/v3