javascript如何生成文档
发布于 3年前 作者 guilin 2266 次浏览

安装了 dox 和 docco, 但是 dox 现在只输出json, docco直接出错.

还有个工具叫 Sphinx, 但是是python的, 不知道如何使用.

各位是如何生成文档的, 求个5分钟教程.

11 回复

docco 依赖 python 和 pygments, 先装好这两个然后在命令行下直接运行 docco yourfilename.js 就会生成 yourfilename.html 文件。

之前还试过 jsdoc,与javadoc 类似,在源码中按照规定的格式写上注释,然后就就可以生成相应的文档。使用帮助: http://code.google.com/p/jsdoc-toolkit/wiki/CommandlineOptions

还有个叫joDoc的,也是用注释生成文档的工具,语法比较简单,xuijs.com上的文档就是用这个生成的,你可以对比下文档和源码,入门很容易

@guilin Sphinx 不是某开源搜索引擎吗?

每次看到 docco 都忍不住想笑… 太多山寨了, 搜集 (>10) 个了
http://learning-notes.diandian.com/post/2012-01-27/16254983

哪个好啊.

@guilin 它们两个定位不同,docco 强调的是文学化编程,方便别人或自己阅读源码。而 jsdoc 强调的是 API 文档的生成,方便用户查阅各个函数用法。

写python绕不过Sphinx的,估计我现在看的一半以上的文档都是用它来生成的吧。但我只是用它的基础功能,研究得不深,以下算是一个5 分钟文档,FYI:

$ sphinx-quickstart

回答一些问题进行初始设置,主要是设置autodoc

> Separate source and build directories (y/N) [n]: y > autodoc: automatically insert docstrings from modules (y/N) [n]: y

现在目录下多出了source和build两个文件夹,编辑index.rst,增加一个rst文件

Contents:

.. toctree::
   :maxdepth: 2

    app

source/app.rst就是用来写文档的文件了,内容可能是:

. js:function:: app.get(route, callback[, errback])

   :param string route: An URI to the location of the resource.
   :param callback: Get's called with the object.
   :param errback:
       Get's called in case the request fails. And a lot of other
       text so we need multiple lines

最后生成文档:

sphinx-build -b html source/ build/

我用的是Sencha ExtJS风格的文档, 工具地址: https://github.com/senchalabs/jsduck

试用了下,效果很好

回到顶部