airflow-doc-zh
airflow-doc-zh copied to clipboard
后续有跟进版本更新的计划吗?
现在最新的stable 是1.10.3,可以看到官方的文档结构和内容都改变了许多 比如把“宏”单独拿出来作为一章了link
有的
的确 1.10.3 官网修改了很多内容,但是我们还没有解决多版本页面的问题,这样会导致新版本将旧版本覆盖掉的情况,这样对用户不太友好。我们针对某个版本的翻译也会丢失
@zhongjiajie
对,所以我想大家讨论下。我现在觉得markdown写起来方便,但官方是用的rst,而且会根据代码生成API的解释,主要还是现在的zh/31.md 以及我刚翻译的zh/28.md 有大量的代码引用,在排版样式上和官网差异较大,特别是函数名,类名用反引号` 生成代码块会有滚动条,看起来不太方便
所以我们会考虑换用rst将格式统一吗?
多版本的问题可以部署在readthedoc平台上,我尝试把第一章部署了一下,这里 看效果,如果需要,我很乐意进一步调研下
@morefreeze 如果用 RST 的话,我就帮不上忙了,因为我没有配套的工具。靠你们了。
rst用来展现API确实会比较好, 我这里列一下优缺点:
优点
- 样式上和官网保持一致
- 支持搜索
- 支持多版本
- 可以使用使用 airflow 的 docs CI 脚本
缺点
- 要重新修改当前的翻译
- rst格式在国内可能没有markdown普及 会使得项目维护者数量变少(important很多项目都是因为缺少新的参与者导致最后走不下去)
欢迎大家补充优缺点, 欢迎使用 :+1: 表示赞成, :-1: 表示反对
看看能不能拿 pandoc 转?
rst
好像用 python
就能直接转成 html
,同建议可考虑做成 rst
模式,airflow
的官网文档应该可以通过查看源的方式获取 rst
文档的原文。
不同版本是不是可以考虑做成不同的分支,master
是最新的版本,别的 branch
可以当作旧版本的翻译的备份
@zhongjiajie 的确 1.10.3 官网修改了很多内容,但是我们还没有解决多版本页面的问题,这样会导致新版本将旧版本覆盖掉的情况,这样对用户不太友好。我们针对某个版本的翻译也会丢失
我们正在考虑把它搬上 crowdin 来解决多版本问题。