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 中轻松浏览最新文档。