javascript - 如何使用 dgeni 生成索引应用程序/文件

Question

我需要记录现有的 AngularJS(1.6.x + Webpack2 + es6-modules)项目，并希望坚持采用众所周知的方式来记录它。例如，就像 AngularJS 本身的记录方式一样。

我很难设置 dgeni。我发现一篇博文Documenting your Angular app using Dgeni in 10 easy steps和一个three year old example project 。

'use strict';

var path = require('canonical-path');
const {Dgeni, Package} = require('dgeni');

var hm = new Package('documentation', [
  require('dgeni-packages/ngdoc'),
  require('dgeni-packages/nunjucks')
])
  .config(function (log, readFilesProcessor, writeFilesProcessor) {
  log.level = 'info';
  readFilesProcessor.basePath = path.resolve(__dirname, '..');
  readFilesProcessor.sourceFiles = [
    {
      include: 'src/main/javascript/**/*.js',
      basePath: 'src/main/javascript'
    },
  ];
  writeFilesProcessor.outputFolder = 'docs/generated';
});
var dgeni = new Dgeni([hm]);

dgeni.generate().then(done);

function done() {
  console.log('done');
}

这会生成一些文档片段，但我缺少将其组合在一起的部分，某种索引页面或导航。博文中有
some example angular app生成一个文档网络应用程序，但由于所有其他部分都需要大量的手动干预才能使其工作，我不想使用最有可能的半完成博客教程作为基础和更喜欢一些易于使用的索引应用程序模板，这些模板作为包提供和更新。

我是否错过了什么，或者 dgeni 的每个普通配置步骤都很难弄清楚？我只需要某种索引。

Answer 1

我创建了一个indexPageProcessor，它收集信息并将其呈现到索引页。

索引页处理器

'use strict';
const _ = require('lodash');
const changeCase = require('change-case');

module.exports = indexPageProcessor;

function indexPageProcessor() {
  return {
    $runAfter: ['paths-computed'],
    $runBefore: ['rendering-docs'],
    $process: process
  };

  function process(docs) {
    const types = {};
    docs.forEach((doc) => {
      types[doc.docType] = types[doc.docType] || [];
      const docData = buildDocData(doc);
      types[doc.docType].push(docData);
    });
    const typeList = [];
    Object.keys(types).forEach((typeName) => {
      typeList.push({
        type: typeName,
        items: types[typeName]
      });
    });

    docs.push({
      baseName: 'index',
      name: 'index',
      template: 'index.template.md',
      outputPath: 'README.md',
      types: typeList
    });
  }
}

function buildDocData(doc) {
  const splitName = doc.name.split('.');
  const stateName = _.camelCase(splitName);
  let displayName = doc.name;
  if (['directive', 'component'].indexOf(doc.docType) >= 0)
    displayName = changeCase.param(doc.name);

  return {
    name: doc.name,
    displayName: displayName,
    stateName: stateName,
    type: doc.docType,
    description: doc.description,
    outputPath: doc.outputPath,
    url: doc.path,
  };
}

Markdown 索引页面模板

# Angular Documentation
{%- if doc.types %}
{%- for type in doc.types %}

# {$ type.type $}
{%- for item in type.items %}
* [{$ item.displayName $}]({$ item.outputPath $})<br>
  {%- if item.description %}
  {$ item.description | firstParagraph $}
  {%- endif -%}{% endfor -%}

{% endfor -%}
{% endif -%}

用于生成文档的主要 Javascript

'use strict';

const path = require('canonical-path');
const {Dgeni, Package} = require('dgeni');

const hm = new Package('documentation', [
  require('dgeni-markdown')
])
  .processor(require('./indexPage'))
  .config(function (log, readFilesProcessor, writeFilesProcessor, templateFinder) {
    log.level = 'warn';
    readFilesProcessor.basePath = path.resolve(__dirname, '..');
    readFilesProcessor.sourceFiles = [
      {
        include: 'src/main/javascript/**/*.js',
        basePath: 'src/main/javascript'
      },
    ];
    templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
    writeFilesProcessor.outputFolder = 'docs/generated';
  });
const dgeni = new Dgeni([hm]);

module.exports = () => dgeni.generate().then(done);

dgeni.generate().then(done);

function done() {
  console.log('Generated documentation.');
}

我使用 markdown 输出，在每次构建期间重新生成它，以便我们可以在 gitlab 中轻松浏览最新文档。