NgDoc 项目常见问题解决方案

NgDoc 项目常见问题解决方案

ng-doc 📃 The documentation engine for Angular projects 项目地址: https://gitcode.com/gh_mirrors/ng/ng-doc

一、项目基础介绍

NgDoc 是一个用于为 Angular 项目生成文档的开源工具。它通过Nunjucks模板引擎，使得生成文档的过程变得简单快捷。NgDoc 支持动态 markdown 模板、在页面中渲染组件演示、创建组件和指令的沙盒环境等功能。项目的编程语言主要是 TypeScript 和 JavaScript。

二、新手常见问题及解决步骤

问题1：如何安装 NgDoc

解决步骤：

1. 确保已经安装了 Node.js 和 npm。
2. 在项目根目录下运行命令 npm install ng-doc --save-dev 来安装 NgDoc。
3. 在项目的 package.json 文件中添加一个脚本来启动 NgDoc，例如：

   "scripts": {
     "doc": "ng-doc"
   }
   

4. 运行 npm run doc 来启动文档生成。

问题2：如何定制文档模板

解决步骤：

1. 在项目中创建一个 ng-doc 文件夹，并在其中添加自定义的模板文件。
2. 修改 ng-doc 的配置文件，通常为 ng-doc.config.js，来指定模板的路径。
3. 在配置文件中，可以设置模板的路径，例如：

   module.exports = {
     templates: {
       src: 'path/to/custom/templates',
       dest: 'path/to/output'
     }
   };
   

4. 重新运行 npm run doc 来生成带有自定义模板的文档。

问题3：如何添加 API 文档

解决步骤：

1. 在需要生成文档的 TypeScript 文件中，为类、方法、属性等添加 JSDoc 注释。
2. 例如，为一个类添加如下注释：

   /**
    * @class MyClass
    * MyClass 的描述
    */
   export class MyClass {
     /**
      * @method myMethod
      * myMethod 的描述
      */
     myMethod() {
       // ...
     }
   }
   

3. 确保在 ng-doc.config.js 中配置了正确的文件路径和文件类型。
4. 运行 npm run doc 后，API 文档将会根据注释生成。

ng-doc 📃 The documentation engine for Angular projects 项目地址: https://gitcode.com/gh_mirrors/ng/ng-doc