项目地址:https://prosemirror.xheldon.com
此为个人项目,用来在本人阅读 ProseMirror 源码过程中加注释和汉化使用
因为原作者 @Marijn 的文档是通过扫描源码生成文档然后放到 官网 上的,因此此处只能通过在源码中添加注释的方式来生成相同的汉化 API 手册。
因为是业余时间做这件事,因此这个进度不确定,不要催更。
本地第一次运行的时候是现 clone
远端仓库,因此需要依次运行:
npm install yarn -g
如果没有安装yarn
的话bin/pm install
因为 ProseMirror官网 整体的静态文件(包括示例、文档手册等)位于 website
的 public
目录下。除了 文档手册 之外,其他内容如示例、指南等页面均固定不变,因此可以直接翻译(这些页面改动频率极低)。
而其 文档手册
是通过逐个将 ProseMirror 子模块
源文件中的 注释识别并生成 成文档手册的,
因此,在 install
后,本地目录会有全部的 ProseMirror
子模块,然后 website
内有 make
命令可以逐个将子模块的源文件中的注释生成成文档手册,
我们只需要在源码中的注释下添加
中文注释即可。同时,因为只在原始注释下新增而不删除,所以直接 merge
原始仓库的后续修改到本仓库不会有冲突。
通过将特定开头的注释识别成中文的方式进行翻译,以保证不删除原始文档而只新增,特定的注释需要遵循以下规则:
- 必须在紧挨着英文原文注释之后,因为中文翻译生成的时候需要找到原文然后将原文放入其内部属性上,以在 hover 的时候能够显示原文
- 必须和英文原文注释隔开一个空行,是为了生成新的
p
标签 - 注释必须以
@cn
开头 - 如果有译者备注,则必须以
@comment
开头
举例:
如下在子模块 prosemirror-view
中(本地路径 ./view/src/index.js
)翻译某个 API,则需要这么做:
// ::- An editor view manages the DOM structure that represents an
// editable document. Its state and behavior are determined by its
// [props](#view.DirectEditorProps).
//
// @cn一个编辑器视图负责整个可编辑文档。它的 state 和行为由 props 决定。
//
// @comment新建编辑器的第一步就是 new 一个 EditorView。
cd
到website
目录- 运行
make
命令 - 运行
npm run devserver -- --prot 8888
- 访问
localhost:8888
查看效果
注:通过修改注释来翻译文档后,因为需要重新生成 doc
,所以需要重启 devserver
,这点后续优化。
在线效果可在:https://prosemirror.xheldon.com/docs/ref/#view.EditorView 查看
如你在 prosemirror-view
子模块中添加了一个 console.log
或者修改了一个逻辑,然后想查看效果,需要直接在根目录下运行:
npm run demo
bin/pm watch
进行实时刷新,即修改了任一模块的src
下的内容后,就会重新打包文件,供demo
使用。- 打开
localhost:8080
查看效果。
注:其他人想翻译需要先 fork
对应的子模块仓库,然后按照上面说的方式进行翻译,完成后提 PR
。下列操作仅限 xheldon-prosemirror 团队成员。
修改完成后,需要 push
到远端,此处我已经修改远端地址为 https://github.com/xheldon-prosemirror/MODULE_NAME
,因此可以通过运行:
bin/pm commit -a -m 'some comment'
将改动commit
bin/pm push
将代码推向远端的xheldon-prosemirror
仓库而不是原ProseMirror
仓库
通过注释的方式翻译好后,如在 ./view/src/index.js
中修改了某个注释,后:
- 依前面步骤
commit
- 自动追加一个文件
X_CHANGELOG.md
,记录本次修改的变动,然后在push
的时候也一起push
到prosemirror
仓库,以此来触发更新(之前push
的时候只会对应发布相关module
,prosemirror
本身不会更新 - 触发
prosemirror
的CI
CI
拉取prosemirror
仓库,然后将当前目录(website
)下的public
push
到https://github.com/Xheldon/prosemirror-doc-cn/
仓库- 稍等片刻后会自动触发
Jekyll
的自动编译生成GitHub Pages
,之后通过访问https://prosemirror.xheldon.com/docs/ref/
来查看生成的文档
注:原示例页面中有一个 协同编辑的示例 ,因为其需要服务端支持而目前不可用
。
以下是原始 README:
[ WEBSITE | ISSUES | FORUM | GITTER ]
ProseMirror is a well-behaved rich semantic content editor based on contentEditable, with support for collaborative editing and custom document schemas.
The ProseMirror library consists of a number of separate modules. This repository just serves as a central issue tracker, and holds a script to help easily check out all the core modules for development.
The project page has more information, a number of examples and the documentation.
This code is released under an MIT license. There's a forum for general discussion and support requests, and the Github bug tracker is the place to report issues.
STOP READING HERE IF YOU'RE SIMPLY USING PROSEMIRROR. YOU CAN INSTALL THE SEPARATE NPM MODULES FOR THAT. THE INSTRUCTIONS BELOW ONLY APPLY WHEN DEVELOPING PROSEMIRROR!
Clone this repository, and make sure you have node and yarn (due to a string of issues with NPM 5, NPM is not currently supported) installed. Next, from the cloned directory run:
bin/pm install
This will fetch the submodules, install their dependencies, and build them.
The bin/pm
script in this repository provides functionality for
working with the repositories:
-
bin/pm build
rebuilds all the modules -
bin/pm watch
sets up a process that automatically rebuilds the modules when they change -
bin/pm status
prints the git status of all submodules -
bin/pm commit <args>
runsgit commit
with the given arguments in all submodules that have pending changes -
bin/pm test
runs the (non-browser) tests in all modules -
bin/pm push
runsgit push
in all modules. -
bin/pm grep <pattern>
greps through the source code for the modules for the given pattern
(Functionality for managing releases will be added in the future.)
To run the demo in demo/
, do npm run demo
, and go to
localhost:8080. This loads the individual
JavaScript files from the distribution's dist
directories, and will
only need a refresh when those are changed.
We aim to be an inclusive, welcoming community. To make that explicit, we have a code of conduct that applies to communication around the project.