build(docs-infra): display github links in CLI API docs (#26515)

This commit includes the following changes:

* CLI version information is read from the CLI package from which
  we read the help files.
* CLI API pages now contain GH links
* line numbers are not shown in GH links, if the doc does not
  have a truthy `startingLine` value. This allows us to remove
  hard coded checks for `guide` pages
* content pages and CLI api docs no longer have a `startingLine`
* the hard-coded `packages` path segment has been removed from
  the templates; instead we now only use the `realProjectRelativePath`.
* the `realProjectRelativePath` has been updated accordingly for API
  and CLI API docs.

PR Close #26515

aio/tools/transforms/angular-api-package/index.js

@@ -34,6 +34,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   .processor(require('./processors/removeInjectableConstructors'))
   .processor(require('./processors/processPackages'))
   .processor(require('./processors/processNgModuleDocs'))
+  .processor(require('./processors/fixupRealProjectRelativePath'))
 
 
   /**

aio/tools/transforms/angular-api-package/processors/fixupRealProjectRelativePath.js

@@ -0,0 +1,14 @@
+module.exports = function fixupRealProjectRelativePath(API_DOC_TYPES) {
+  return {
+    $runAfter: ['readTypeScriptModules'],
+    $runBefore: ['processing-docs'],
+    $process(docs) {
+      docs.forEach(doc => {
+        if (API_DOC_TYPES.indexOf(doc.docType) !== -1 && doc.fileInfo && doc.fileInfo.realProjectRelativePath) {
+          // this is an API doc - so fix up its real path
+          doc.fileInfo.realProjectRelativePath = 'packages/' + doc.fileInfo.realProjectRelativePath;
+        }
+      });
+    }
+  };
+};

aio/tools/transforms/angular-api-package/processors/fixupRealProjectRelativePath.spec.js

@@ -0,0 +1,36 @@
+const testPackage = require('../../helpers/test-package');
+const processorFactory = require('./fixupRealProjectRelativePath');
+const Dgeni = require('dgeni');
+
+describe('fixupRealProjectRelativePath processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('fixupRealProjectRelativePath');
+    expect(processor.$process).toBeDefined();
+    expect(processor.$runAfter).toContain('readTypeScriptModules');
+    expect(processor.$runBefore).toContain('processing-docs');
+  });
+
+  it('should add `packages` segment to the start of `realProjectRelativePath` for API docs', () => {
+    const processor = processorFactory(['class', 'member']);
+    const docs = [
+      { docType: 'class', fileInfo: { realProjectRelativePath: 'a/b/c' } },
+      { docType: 'member', fileInfo: { realProjectRelativePath: 'a/b/c/d' } },
+      { docType: 'cli-command', fileInfo: { realProjectRelativePath: 'a/b/c' } },
+      { docType: 'class', fileInfo: { } },
+      { docType: 'class' },
+    ];
+    processor.$process(docs);
+
+    expect(docs).toEqual([
+      { docType: 'class', fileInfo: { realProjectRelativePath: 'packages/a/b/c' } },
+      { docType: 'member', fileInfo: { realProjectRelativePath: 'packages/a/b/c/d' } },
+      { docType: 'cli-command', fileInfo: { realProjectRelativePath: 'a/b/c' } },
+      { docType: 'class', fileInfo: { } },
+      { docType: 'class' },
+    ]);
+  });
+});
+

aio/tools/transforms/cli-docs-package/index.js

@@ -3,7 +3,9 @@ const Package = require('dgeni').Package;
 const basePackage = require('../angular-base-package');
 const contentPackage = require('../content-package');
 const {CONTENTS_PATH, TEMPLATES_PATH, requireFolder} = require('../config');
-
+const CLI_SOURCE_ROOT = resolve(CONTENTS_PATH, 'cli-src');
+const CLI_SOURCE_PATH = resolve(CLI_SOURCE_ROOT, 'node_modules/@angular/cli');
+const CLI_SOURCE_HELP_PATH = resolve(CLI_SOURCE_PATH, 'help');
 
 // Define the dgeni package for generating the docs
 module.exports = new Package('cli-docs', [basePackage, contentPackage])
@@ -18,12 +20,11 @@ module.exports = new Package('cli-docs', [basePackage, contentPackage])
 
 // Configure file reading
 .config(function(readFilesProcessor, cliCommandFileReader) {
-  const CLI_SOURCE_PATH = resolve(CONTENTS_PATH, 'cli-src/node_modules/@angular/cli/help');
   readFilesProcessor.fileReaders.push(cliCommandFileReader);
   readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([
     {
-      basePath: CLI_SOURCE_PATH,
+      basePath: CLI_SOURCE_HELP_PATH,
-      include: resolve(CLI_SOURCE_PATH, '*.json'),
+      include: resolve(CLI_SOURCE_HELP_PATH, '*.json'),
       fileReader: 'cliCommandFileReader'
     },
     {
@@ -42,6 +43,23 @@ module.exports = new Package('cli-docs', [basePackage, contentPackage])
 })
 
 
+.config(function(renderDocsProcessor) {
+
+  const cliPackage = require(resolve(CLI_SOURCE_PATH, 'package.json'));
+  const repoUrlParts = cliPackage.repository.url.replace(/\.git$/, '').split('/');
+  const version = `v${cliPackage.version}`;
+  const repo = repoUrlParts.pop();
+  const owner = repoUrlParts.pop();
+  const cliVersionInfo = {
+    gitRepoInfo: { owner, repo },
+    currentVersion: { raw: version }
+  };
+
+  // Add the cli version data to the renderer, for use in things like github links
+  renderDocsProcessor.extraData.cliVersionInfo = cliVersionInfo;
+})
+
+
 .config(function(convertToJsonProcessor, postProcessHtml) {
   convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(['cli-command', 'cli-overview']);
   postProcessHtml.docTypes = postProcessHtml.docTypes.concat(['cli-command', 'cli-overview']);

aio/tools/transforms/cli-docs-package/readers/cli-command.js

@@ -15,6 +15,7 @@ module.exports = function cliCommandFileReader(log) {
     name: 'cliCommandFileReader',
     defaultPattern: /\.json$/,
     getDocs(fileInfo) {
+      fileInfo.realProjectRelativePath = 'packages/angular/cli/commands/' + fileInfo.relativePath;
       try {
         const doc = json5.parse(fileInfo.content);
         const name = fileInfo.baseName;
@@ -23,7 +24,6 @@ module.exports = function cliCommandFileReader(log) {
         const result = Object.assign(doc, {
           content: doc.description,
           docType: 'cli-command',
-          startingLine: 1,
           id: `cli-${doc.name}`,
           commandAliases: doc.aliases || [],
           aliases: computeAliases(doc),

aio/tools/transforms/cli-docs-package/readers/cli-command.spec.js

@@ -82,11 +82,6 @@ describe('cli-command reader', () => {
       ]);
     });
 
-    it('should start at line 1', () => {
-      const docs = reader.getDocs(fileInfo);
-      expect(docs[0].startingLine).toEqual(1);
-    });
-
     it('should extract the short description into the content', () => {
       const docs = reader.getDocs(fileInfo);
       expect(docs[0].content).toEqual('Add support for a library to your project.');

aio/tools/transforms/content-package/readers/content.js

@@ -18,7 +18,7 @@ module.exports = function contentFileReader() {
     getDocs: function(fileInfo) {
 
       // We return a single element array because content files only contain one document
-      return [{docType: 'content', content: fileInfo.content, startingLine: 1}];
+      return [{docType: 'content', content: fileInfo.content}];
     }
   };
 };

aio/tools/transforms/content-package/readers/content.spec.js

@@ -37,7 +37,7 @@ describe('contentFileReader', function() {
           'project/path/modules/someModule/foo/docs/subfolder/bar.ngdoc', 'A load of content',
           'project/path');
       expect(fileReader.getDocs(fileInfo)).toEqual([
-        {docType: 'content', content: 'A load of content', startingLine: 1}
+        {docType: 'content', content: 'A load of content'}
       ]);
     });
   });

aio/tools/transforms/templates/cli/cli-command.template.html

@@ -1,6 +1,8 @@
 {% import 'lib/cli.html' as cli %}
+{% import "../lib/githubLinks.html" as github -%}
 
 <article>
+  {$ github.githubLinks(doc, cliVersionInfo) $}
   {% include 'include/cli-breadcrumb.html' %}
   {% include 'include/cli-header.html' %}
 

aio/tools/transforms/templates/lib/githubLinks.html

@@ -3,16 +3,21 @@
 {%- endmacro %}
 
 {% macro githubViewHref(doc, versionInfo) -%}
-https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/{$ versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw $}/packages/{$ doc.fileInfo.realProjectRelativePath $}#L{$ doc.startingLine + 1 $}-L{$ doc.endingLine + 1 $}
+{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
+{% set version = versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw -%}
+{% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
+{$ githubUrl $}/tree/{$ version $}/{$ projectRelativePath(doc.fileInfo) $}{$ lineInfo $}
 {%- endmacro %}
 
-{% macro githubEditHref(doc, versionInfo) -%}
+{% macro githubEditHref(doc, versionInfo, pathPrefix) -%}
-https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/edit/master{$ '/packages' if doc.docType !== 'content' $}/{$ projectRelativePath(doc.fileInfo) $}?message=docs
+{% set githubUrl = 'https://github.com/' + versionInfo.gitRepoInfo.owner + '/' + versionInfo.gitRepoInfo.repo -%}
+{% set lineInfo = doc.startingLine and ('#L' + (doc.startingLine + 1) + '-L' + (doc.endingLine + 1)) or '' -%}
+{$ githubUrl $}/edit/master/{$ projectRelativePath(doc.fileInfo) $}?message=docs
   {%- if doc.moduleDoc %}({$ doc.moduleDoc.id.split('/')[0] $})
   {%- elseif doc.docType === 'module' %}({$ doc.id.split('/')[0] $})
   {%- elseif doc.docType === 'content' %}
   {%- else %}(...){%- endif -%}
-%3A%20describe%20your%20change...{% if doc.docType !== 'content' %}#L{$ doc.startingLine + 1 $}-L{$ doc.endingLine + 1 $}{% endif %}
+%3A%20describe%20your%20change...{$ lineInfo $}
 {%- endmacro %}
 
 {% macro githubEditLink(doc, versionInfo) -%}

scripts/ci/test-aio-tools.sh

@@ -10,6 +10,7 @@ source ${thisDir}/_travis-fold.sh
 travisFoldStart "test.docs"
   (
     cd ${PROJECT_ROOT}/aio
+    yarn setup
     yarn tools-test
   )
 travisFoldEnd "test.docs"