V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
V2EX 提问指南
nl101531
V2EX  ›  问与答

项目文档跟着项目走有什么好的方案?

  •  
  •   nl101531 · 2018-03-02 16:20:30 +08:00 · 2641 次点击
    这是一个创建于 2218 天前的主题,其中的信息可能已经有所发展或是发生改变。

    主要是项目迭代技术方案,接口文档之类的. 之前是放在 wiki 平台上,但是关联起来麻烦,每一次找文档基本是 wiki 平台全文搜索,而且更新会不及时.

    然后想法是让文档跟着项目走,文档再项目内部,git 管理,然后公司全部使用的是 IDEA,开发个插件把文档与对应的代码关联起来.

    展示层打算用 https://docsify.js.org/ , 有其他好的建议不

    6 条回复    2018-03-04 12:06:08 +08:00
    virusdefender
        1
    virusdefender  
       2018-03-02 17:55:12 +08:00   ❤️ 2
    https://strcpy.me/index.php/archives/772/

    我以前的经验,测试过了,文档就是正确的
    Icezers
        2
    Icezers  
       2018-03-02 18:20:33 +08:00 via iPhone
    Mark
    daemonghost
        3
    daemonghost  
       2018-03-02 19:45:23 +08:00   ❤️ 1
    可以用 GitBook 来整理项目文档,如果只是单纯的 API 接口文档,可以试试 swagger: https://swagger.io/
    mcfog
        4
    mcfog  
       2018-03-02 20:09:32 +08:00 via Android
    能和代码直接对应的起来的大概也就是 api 和 db schema 了,api 我以前写过一些看法 http://press.mcfog.wang/2015/02/my-api-programming-style/ db 相关的还没写成文章,但思路是类似的
    clip
        5
    clip  
       2018-03-03 01:28:18 +08:00 via Android
    接口文档准备用类似 https://github.com/marshmallow-code/apispec 里面的做法,定义好 schema、在 route 函数上写注释,最后生成 OpenAPI 格式的文档。

    技术方案的话不大喜欢放代码里,还是放在 wiki 里把链接到代码里。
    nl101531
        6
    nl101531  
    OP
       2018-03-04 12:06:08 +08:00
    @daemonghost API 文档使用 swagger 管理,这里主要是项目文档比如迭代技术方案之类的.


    @clip 感谢,wiki 贴链接总觉得很麻烦.目前打算文档放项目中,ci 时上传到公共服务器 nginx 路由下展示. 而代码中开发了一个 IDEA 插件,使用特殊注释与指定文件关联起来.
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   1506 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 25ms · UTC 23:53 · PVG 07:53 · LAX 16:53 · JFK 19:53
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.