概要 Read the Docs 出品了一个新项目，用于为上传到Python Package Index的代码自动生成API文档． Read the Docs, 一个著名的社区支持的创建易读的在线文档的服务商，公开了他们的新项目Pydoc，这个新项目能够自动为上传到PyPI上的代码创建API文档． 这个项目的维护者在博客中写道：＂有很多场景下，需要API文档的支持，但是Python社区没有提供很好的API文档．＂像Ruby和Go这类语言已经有了自己类似的文档服务网站，现在Python社区也有了． 你看文档么？ Pydoc获取PyPI上的Python软件包，并用sphinx文档生成引擎来解析软件包的源代码．如果源代码中有符合Python的Docstring约定的文档，Pydoc就为这个软件包生成一个树形的可浏览的在线文档．对于没有文档的API，Pydoc会把该API的函数签名列在文档里． Read the Docs目前的服务主要针对项目的高层文档，这些文档往往是项目维护者编写的，而不是从源代码自动生成的． Pydoc这个项目在两个方面上与原有服务不同．第一个方面，它的文档是自动从PyPI包的源代码中生成的：PyPI上的项目，只要有正确的docstring，那么它们都可以无需人工干预地生成文档．第二个方面，这个项目提供了一个场所让开发者更方便地查阅文档，而不用去浏览源代码．当然你还是可以去阅读源码，从PyPI网站上下载源码阅读就好了，不过使用Pydoc你就不用解压源代码了． 还有点混乱 不是所有东西都工作得很好，＂目前还只是Beta版＂，该项目的开发者在博客中说．这个服务如何跟PyPI集成，并且如何处理私有方法和变量，这些工作还在进行中． 更重要的是，该项目目前使用的技术还不适合大规模部署．目前项目代码还需要导入到一个运行的Python实例中才能够遍历和解析． 对于比较小的项目，比如pytz，这个方法还可以．但是对于复杂的项目，比如numpy这样涉及大量C库的项目，就不切实际了．面对这种情况，Pydoc的开发者们在考虑要不要构建一个自定义的解释器来作为一个长期的解决方案，不过目前还没有一个工期上很好的方案可以解决这个问题．
|
|
声明：文章版权归原作者所有 部分文章转自互联网 如有侵权请联系
[邮箱地址] 删除
|
注册
登录
