如何使用 grunt-ngdocs 创建 api 文档

Posted 2023-03-07

【中文标题】如何使用 grunt-ngdocs 创建 api 文档

【英文标题】：How to create api documents with grunt-ngdocs

【发布时间】：2014-09-13 14:34:51

【问题描述】：

我正在尝试通过 grunt-ngdocs 创建 API 文档。 部分已创建，但 index.html 没有正确的链接。

我的 gruntfile.js 中有：

module.exports = function (grunt) 

grunt.initConfig(
    pkg: grunt.file.readJSON('package.json'),
    karma: 
        unit: 
            configFile: 'karma.conf.js'
        
    ,
    uglify: 
        options: 
            // the banner is inserted at the top of the output
            banner: '/*! <%= pkg.name %> <%= grunt.template.today("dd-mm-yyyy") %> */\n'
        ,
        dist: 
            files: 
                'web/js/app.min.js': ['web/js/app.js']
            
        
    ,
    ngdocs: 
        options: 
            dest: 'docs',
            scripts: ['web/js/app.js'],
            title: 'My Documentation'
        ,
        api: 
            src: ['web/**/*.js'],
            title: 'API Documentation'
        
    ,
    clean:['docs','testResult']


);

grunt.loadNpmTasks('grunt-karma');
grunt.loadNpmTasks('grunt-ngdocs');
grunt.loadNpmTasks('grunt-contrib-uglify');
grunt.loadNpmTasks('grunt-contrib-clean');
grunt.registerTask('default', ['clean','uglify', 'ngdocs', 'karma']);
;

和我这样的js文件

 /**
  * @ngdoc overview
  * @ngdoc directive
  * @name myApp.maincontroller:controller
  * @description
  *
  * # myApp
  * The factoryName is my favorite service in the world.
  *
  */


 var myApp = angular.module('myApp',[]);


 myApp.controller("MainController", function($scope) 
    $scope.model = 
        myValue: "Run you fools!"
    ;
   );


 /**
          * @ngdoc function
          * @name mySuperFunction
          * @returns int The int representing a Firebase resource
          */

 function mySuperFunction() 
    var i = 5;
    var j = 5;
    i += j;
    return i;
  

但是当我运行时

grunt 

在命令行中，结果是这样的

 C:\Users\Lino Simões\Documents\bitbucket\test>grunt -d --force
 Running "clean:0" (clean) task
 [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\test\node_modules\grun
 t-contrib-clean\tasks\clean.js
 Cleaning docs...OK

 Running "clean:1" (clean) task
 [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\test\node_modules\grun
 t-contrib-clean\tasks\clean.js
 Cleaning testResult...OK

 Running "uglify:dist" (uglify) task
 [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\test\node_modules\grun
 t-contrib-uglify\tasks\uglify.js
 File web/js/app.min.js created: 796 B → 210 B

 Running "ngdocs:api" (ngdocs) task
 [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\test\node_modules\grun
 t-ngdocs\tasks\grunt-ngdocs.js
 Generating Documentation...
 DONE. Generated 2 pages in 256ms.

 Running "karma:unit" (karma) task
 [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\test\node_modules\grun
 t-karma\tasks\grunt-karma.js
 INFO [karma]: Karma v0.12.17 server started at http://localhost:9876/
 INFO [launcher]: Starting browser PhantomJS
 INFO [PhantomJS 1.9.7 (Windows 7)]: Connected on socket dFX-dKGVINA6PBjB5Gu9 wit
 h id 91061839
 PhantomJS 1.9.7 (Windows 7): Executed 8 of 8 SUCCESS (0.008 secs / 0.004 secs)

 Done, without errors.

所以，这会生成 2 个文件，但是当我转到文档下的 index.html 时，我有这个：

但在我的 docs/partials/api/ 中，我有 ngdocs 创建的部分。

我的项目树是这样的：

【参考方案1】：

您的 web/js/app.js 中有 angular.js 和 angular-animate.js 吗？检查。并添加到“选项”html5Mode: false

【讨论】：

我添加了html5Mode:false 和bestMatch: true。将scripts: ['web/js/app.js'] 更改为scripts: ['lib/angular.js']，就是这样。创建部分，但 index.html 等于上面的

控制台有什么异常？

无，我在控制台的输出是这样的：Running "ngdocs:api" (ngdocs) task [D] Task source: C:\Users\Lino Simões\Documents\bitbucket\jenkins-test\node_modules\grunt-ngdocs\tasks\grunt-ngdocs.js Generating Documentation... DONE. Generated 2 pages in 424ms.

打开文档时在浏览器中检查控制台

我将 angular-animate 放在另一个目录中，一旦我放入正确的目录，效果就很好了。

【参考方案2】：

ng1.6 适合我：

ngdocs: 
  all: ['app/**/*.js']

你会在

中看到旧版本的angular 1.2.*

cat docs/js/angular.min.js  | grep v1
 AngularJS v1.2.16

但它不会影响您的源文件。

另外，别忘了运行服务器 对于生成的文件夹文档：

例如使用python

pushd ./dist; python -m SimpleHTTPServer 9000; popd #v 2.*
pushd ./dist; python -m http.server 9000; popd #v 3.*

不幸的是，将 angular.js 和 angular-animate.js 添加到脚本选项对我不起作用