Koo*_*obz 9 python documentation python-sphinx
所以我已经习惯了Javadoc风格的文档.通过各种Python代码示例,我发现,乍一看,文档似乎缺少很多信息.
好处:变化很少你看到不言而喻的文档.Docstrings通常是一段或更少的英文标记,它集成而不是在单独的行上突出.
糟糕的是:结合Python的鸭子打字,我发现许多函数都不清楚他们期望的参数.没有类型提示(duck-hinting？),并且经常会有一些想法,让参数应该像列表一样,类似字符串,像流一样.
当然,Javadoc是为较低级别的语言而设计的,没有Python的强大内省能力,这可能解释了较为冗长的文档哲学.
有关Python文档标准和最佳实践的任何建议吗？
该新结构化格式旨在响应需要Python文档,可以被嵌入到文档字符串,所以最好的办法是学习休息和与该格式格式化文档字符串.你可能会发现,就像我一样,然后你继续格式化reST中的任何文档,但这是一个侧面点:-)
为了专门记录您的Python代码,Sphinx系统是一组reST格式的扩展,以及一个用于呈现文档的构建系统.由于它的设计目的是为了记录Python本身,包括标准库,因此Sphinx允许对源代码进行结构良好的文档编制,当然也包括函数签名的具体细节.它允许构建全面的文档套件,包括自动提取和手写,都使用相同的格式化系统.
如果你只是想从你的源代码生成的文档,然后epydoc的将提取您的源代码API文档 ; 它也会读取文本的reST格式.
| 归档时间： |
|
| 查看次数： |
3982 次 |
| 最近记录： |