- 作者:
- 分类:知识&开发->工具->文档工具
- 阅读:1704
- 点赞:1
- 版权:CC BY-SA 4.0
- 创建:2019-10-14
- 更新:2020-03-17
原文链接(持续更新):https://neucrack.com/p/175
前言
gitbook使用markdown语法进行写作,自动生成简单漂亮的文档页面,还有海量插件可以使用,并且公开文档都免费提供服务,
使用起来很方便,有配套的软件,就算不懂代码的人用起来也非常简单。
但是有个缺点就是国内访问很慢,慢得连github的pages页面的速度都不如,而且不支持同步github组织的仓库,所以可以考虑将gitbook编译成静态页面发布到pages,
而且希望整个发布过程都是自动的,我们自己后面该文档时要做的就只是写文档(直接文本编辑器或者gitbook编辑器都行),写完后提交推送到github,后面的构建、发布全都不用我们自己操作,都自动完成,于是可以用travis,travis对github十分友好,对于公开的仓库,travis也是免费的
方法和步骤
- 首先保证注册了github(github.com)账号、travis(travis.org)账号
- 在github建立文档仓库
- travis开启同步
- 设置travis项目
设置项目变量
这些变量的名字和功能取决于yml脚本,这里这几个变量含义如下:
GITHUB_TOKEN : github授权码,在github的Settings -> Developer settings -> Personal access tokens
中可以生成一个新的 token,注意一定不能勾选Display Value in build log
GIT_NAME,GIT_EMAIL:昵称和邮箱
CUSTOM_DOMAIN:自定义域名,最后github pages中CNAME文件中的内容
- 设置文档工程(仓库)
github仓库新建.travis.yml
文件:
language: node_js
node_js:
- "8"
# 缓存依赖
cache:
directories:
- $HOME/.npm
before_install:
- export TZ='Asia/Shanghai' # 更改时区
# 依赖安装
install:
- npm install gitbook-cli -g
# 安装 gitbook 插件
- gitbook install
# 构建脚本
script:
# 自定义输出目录 gitbook build src dest
- gitbook build . ./build
# - gitbook build . ./build/$CUSTOM_PATH
# 分支白名单
branches:
only:
- master # 只对 master 分支进行构建
# GitHub Pages 部署
deploy:
provider: pages
skip_cleanup: true
# 在项目仪表盘的 Settings -> Environment Variables 中配置
github_token: $GITHUB_TOKEN
# 将 build 目录下的内容推送到默认的 gh-pages 分支上,并不会连带 build 目录一起
local_dir: build
#fqdn: $CUSTOM_DOMAIN
name: $GIT_NAME
email: $GIT_EMAIL
on:
branch: master
这里CUSTOM_PATH
被注释了,如果想域名后面还有子文件夹就这样使用,比如自定义域名gprs.neucrack.com
,不使用CUSTOM_PATH
,则最后的访问地址就是gprs.neucrack.com
,而用了CUSTOM_PATH
而且设置CUSTOM_PATH
变量值为doc
,则最后访问地址就是gprs.neucrack.com/doc
,
上面的代码自定义域名我也注释了,因为没有使用,如果使用自定义域名就取消注释
还需要注意的是,在进行部署的过程中,默认是使用 git push —force 进行推送的,也就是说你的目标分支的历史提交记录只会有最新的那一条,如果需要提交历史的话,可以添加 keep-history: true 选项。
- 推送更新
将新建的.travis.yml
文件同步到github,会自动触发travis对项目的构建
构建成功后便可以在自定义的域名访问了,通常地址为:用户名/组织名.github.io/项目名,如果使用了类似上面的CUSTOM_PATH
的文件夹地址,则访问地址是:用户名/组织名.github.io/项目/CUSTOM_PATH
比如这里有个例子:
构建目标仓库是:https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC
没有使用自定义域名以及文件路径,最后访问地址是:https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/
为了让gitbook能同时有中文和英文,官方有做多语言:Multi-Languages,但是缺点是不能使用语言特殊的插件了.
可以在一个工程中建立两个文件夹,比如en和zh两个文件夹,然后每个文件夹内放一个gitbook工程,这样生成后就会有中英文目录了,这种方法简单方便,中英文在同一个分支进行维护.
另外一种方式,为了让两种语言为两个独立的工程(/分支),将两种语言放在两个分支上,为了将两个分支编译后合并到一个分支的两个文件夹(zh和en),需要自己写脚本,稍微复杂一点,优点是两个分支可以分开提交互不影响向,不爱折腾不建议用这种方式;可以参考:https://github.com/Ai-Thinker-Open/GPRS_C_SDK_DOC,生成的页面地址是:https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/zh 和 https://ai-thinker-open.github.io/GPRS_C_SDK_DOC/en.
可以参考另一个仓库:MAIXPY Doc, 这份文档系统包含了多语言和多版本支持,做得比较全面
也可以参考cocos creator的文档