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

[nl101531]

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

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

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

[virusdefender]

https://strcpy.me/index.php/archives/772/

我以前的经验，测试过了，文档就是正确的

[Icezers]

Mark

[daemonghost]

可以用 GitBook 来整理项目文档，如果只是单纯的 API 接口文档，可以试试 swagger: https://swagger.io/

[mcfog]

能和代码直接对应的起来的大概也就是 api 和 db schema 了，api 我以前写过一些看法 http://press.mcfog.wang/2015/02/my-api-programming-style/ db 相关的还没写成文章，但思路是类似的

[clip]

接口文档准备用类似 https://github.com/marshmallow-code/apispec 里面的做法，定义好 schema、在 route 函数上写注释，最后生成 OpenAPI 格式的文档。

技术方案的话不大喜欢放代码里，还是放在 wiki 里把链接到代码里。

[nl101531]

@daemonghost API 文档使用 swagger 管理,这里主要是项目文档比如迭代技术方案之类的.


@clip 感谢,wiki 贴链接总觉得很麻烦.目前打算文档放项目中,ci 时上传到公共服务器 nginx 路由下展示. 而代码中开发了一个 IDEA 插件,使用特殊注释与指定文件关联起来.