由于上了新项目,项目上对技术文档有要求;故整理了一下,供参考
技术文档有两种,一种就是纯手打Word,另一种就是通过插件脚本或应用程序读取项目文件配合注释生成,今天只说第二种...
如果你是OC同学,有三种方式可以生成HTML格式的技术文档,appledoc,headerdoc,doxygen,再重申一下,这三个工具在我写这篇博客的当下(2021年2月27号),不支持swift!不支持swift!不支持swift! 想看swift的同学往下翻,再往下还有别的
注释格式略过,请自行查阅...
上干货:
1.appledoc
安装appledoc:
1.gitclonegit://github.com/tomaz/appledoc.git
2.cd 项目根路径
3.sudo sh install-appledoc.sh
4.等
5.大写的注意:这样安装最好能改,位置跟./library平级,找appledoc/Model/CBMethodData.m,把第44行"NSParameterAssert([arguments count] >= 1);"注释掉,不然会报错
项目配置:要加个target,然后在新的target里加一个run script,把shell写进去后,cmd+b
shell:
company="公司名";
companyID="公司别名";
companyURL="网址";
target="iphoneos";
#target="macosx";
outputPath="导出路径";
# End constants
/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
"${PROJECT_DIR}"
去操作终端:
1.cd 工程根目录
2.appledoc -o 导出目录 --project-name 项目名(随便写) --project-company 所有者(公司名,随便写) ./
注意:1.生成命令后面要那个"./" ; 2.导出位置如果没找到,去翻developer咱们清xcode缓存的那个目录,找多出来那个扎眼的文件夹/share,然后进到最后面点右键.docset文件"显示包内容";
2.headerdoc
安装:不用装,xcode自带,苹果指定doc工具;
终端:
1.cd 工程根目录
2.headerdoc2html -o 文档导出路径 项目根目录
3.gatherheaderdoc 导出路径
注意:1.如果第二行命令走了报错,如果你正好用的xcode12这种比较新的版本,该命令用到的perl会有多个版本,太高的会报宽字符错误,目前我尝试的最低的可用版本是5.18 ,新开个终端输入:defaults write com.apple.versioner.perl Version 5.18 ,然后再来一遍命令就行了;2.看好命令,中间有空格的;3.不需要像appledoc一样加target去写shell,网上好多同学都说要写,其实用不上;
3.doxygen
这个需要下载一下.dmg...不用安装,直接点开使用就行了
doxygen IDE
1.进到IDE里,上面有个很长的输入框"specify the working...",点右边的select...,选"/Application";
2.三个"wizard","expert","run";
3.先选wizard,左边选project配置下,输入项目名,然后勾选"scan recursively";
4.左边选mode,上面选"All Entities",下面选第一个C++的
3.左边选output,上面勾选HTML且选第一个,下面latex不选;
4.左边选diagrams 选use build-in
5.选run,点run doxygen
6.等
注意:1.这个doxygen格式很舒服,也能自定义,可视化做的很人性,建议用这个,虽然更复杂操作的实现比较繁琐,可以慢慢学,有点老但是挺好用的;2.也有依赖的问题,gem,Perl啥的版本看清楚
现在该swift同学了...
两种:sourcesdocs,jazzy
不推荐sourcesdocs,全是单个.md 也没个索引
jazzy:
安装:
1.sudo brew install jazzy
终端:
1.cd 项目根路径
2.jazzy -x -workspace,工程名.xcworkspace,-scheme,你的scheme--min-acl internal
注意:第二行是我从Git上的issues上面扒出来的,有的小伙伴的"jazzy --min-acl internal ",在我的电脑上确实跑不起来.报错是"armv64"和"armv7".这块不细说了.
最后最后,说说OC-Swift 混编项目...目前唯一能合并OC和swift文档的就是jazzy,么有第二家.
