如何使用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 生成一个文档Web应用程序，但由于所有其他部分需要大量的人工干预才能使它们正常工作，我不想使用最有可能完成的半完成博客教程作为基础和 宁愿像一些易于使用的模板用于作为包提供和更新的索引应用程序。

我是否会遗漏某些东西，或者只是每一个普通的配置步骤都会让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,
  };
}

降价指数页面模板

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