python 项目大家都是如何维护文档的?

[gkiwi]

这里说的不是开源库,而是指一群人做的公司私有项目.

文档不仅是给python开发的同伴看,你还需要把文档维护起来给安卓,IOS,web以及其他人看,大家在这方面有什么心得?

一般我是我是一个窗口维护markdown,iterm2这边用vim写着代码.
也许平时这也没什么,不过现在我给团队重构代码,业务代码进行的很快(东西不多也不复杂),但是当我连写了5个接口,以及5个小文档结构的时候,已经感觉很机械了,特别是来回切换总是不大舒服...;

现在考虑是否将文档直接维护到代码doc里面然后通过pyment输出,但是怕把代码文件拉的太长(虽然很多开源项目都是这样子的),大家在这方面用过的有啥感受?
或者有没有更好的建议分享下..

[piglei]

我在前公司使用的方案是写在每一个View class的docstring里，使用markdown格式，另外有一个脚本扫描这些docstring生成文档，供参考。

[bcxx]

sphinx 这样不行么？

[bigzhu]

sphinx
顺便推销下我的 blog
用sphinx将python的注释生成文档: http://bigzhu.org/blog/%E7%94%A8sphinx%E5%B0%86python%E7%9A%84%E6%B3%A8%E9%87%8A%E7%94%9F%E6%88%90%E6%96%87%E6%A1%A3

[zeayes]

trac wiki

[pythoner]

同三楼

[GeekGao]

wiki

[tolerious]

Mark

[gkiwi]

@bcxx
@bigzhu
@pythoner

sphinx没用过,不是特别喜欢那种输出文档的风格...;

主要还是希望的还是抽离出API接口给其他伙伴用,决定采用1L的方案,自己可以解析相关装饰器的东西...

[gkiwi]

@GeekGao
@tolerious

来回切换文档很痛苦的说..决定采用1L方案.

[bcxx]

@gkiwi sphinx 可以做到 1 楼的效果……虽然是 rst

[gkiwi]

@bcxx 语法不一样...还是喜欢md..

比如这样子:

[bcxx]

@gkiwi 那可以试试用 pycco / docco 之类的（虽然还比较搓

[gkiwi]

@bcxx 谢谢.