V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
推荐学习书目
Learn Python the Hard Way
Python Sites
PyPI - Python Package Index
http://diveintopython.org/toc/index.html
Pocoo
值得关注的项目
PyPy
Celery
Jinja2
Read the Docs
gevent
pyenv
virtualenv
Stackless Python
Beautiful Soup
结巴中文分词
Green Unicorn
Sentry
Shovel
Pyflakes
pytest
Python 编程
pep8 Checker
Styles
PEP 8
Google Python Style Guide
Code Style from The Hitchhiker's Guide
gkiwi
V2EX  ›  Python

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

  •  
  •   gkiwi · 2014-10-17 19:38:10 +08:00 · 3310 次点击
    这是一个创建于 3690 天前的主题,其中的信息可能已经有所发展或是发生改变。
    这里说的不是开源库,而是指一群人做的公司私有项目.

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

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

    现在考虑是否将文档直接维护到代码doc里面然后通过pyment输出,但是怕把代码文件拉的太长(虽然很多开源项目都是这样子的),大家在这方面用过的有啥感受?
    或者有没有更好的建议分享下..
    13 条回复    2014-10-21 12:09:52 +08:00
    piglei
        1
    piglei  
       2014-10-17 21:14:11 +08:00   ❤️ 1
    我在前公司使用的方案是写在每一个View class的docstring里,使用markdown格式,另外有一个脚本扫描这些docstring生成文档,供参考。
    bcxx
        2
    bcxx  
       2014-10-17 21:30:39 +08:00   ❤️ 1
    sphinx 这样不行么?
    bigzhu
        3
    bigzhu  
       2014-10-17 21:48:48 +08:00   ❤️ 2
    zeayes
        4
    zeayes  
       2014-10-18 01:21:39 +08:00
    trac wiki
    pythoner
        5
    pythoner  
       2014-10-18 14:30:28 +08:00   ❤️ 1
    同三楼
    GeekGao
        6
    GeekGao  
       2014-10-18 15:41:09 +08:00
    wiki
    tolerious
        7
    tolerious  
       2014-10-18 16:12:51 +08:00
    Mark
    gkiwi
        8
    gkiwi  
    OP
       2014-10-18 17:14:46 +08:00
    @bcxx
    @bigzhu
    @pythoner

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

    主要还是希望的还是抽离出API接口给其他伙伴用,决定采用1L的方案,自己可以解析相关装饰器的东西...
    gkiwi
        9
    gkiwi  
    OP
       2014-10-18 17:38:49 +08:00
    @GeekGao
    @tolerious

    来回切换文档很痛苦的说..决定采用1L方案.
    bcxx
        10
    bcxx  
       2014-10-18 18:55:58 +08:00
    @gkiwi sphinx 可以做到 1 楼的效果……虽然是 rst
    gkiwi
        11
    gkiwi  
    OP
       2014-10-20 09:44:04 +08:00
    @bcxx 语法不一样...还是喜欢md..

    比如这样子:

    bcxx
        12
    bcxx  
       2014-10-20 17:45:35 +08:00
    @gkiwi 那可以试试用 pycco / docco 之类的(虽然还比较搓
    gkiwi
        13
    gkiwi  
    OP
       2014-10-21 12:09:52 +08:00
    @bcxx 谢谢.
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   实用小工具   ·   1131 人在线   最高记录 6679   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 23ms · UTC 18:39 · PVG 02:39 · LAX 10:39 · JFK 13:39
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.