本文档包含了 Fabric 文档如何建立、发布以及在修改文档前应注意的约定事项等信息。
本文档核心部分采用 reStructuredText
编写,并可使用 Sphinx 转换至HTML格式。
HTML文件发布在 http://hyperledger-fabric.readthedocs.io上。该站点使用了钩子程序,
主仓库 docs/source
目录下的任何新内容都会触发一次对该文档新的构建与发布。
docs/source
目录下。注意:以上约定信息意味着我们需要依赖于 github 镜像仓库。 当通过 RST 文件浏览时,相对链接无法在 github 上正常使用。
和修改生产版本一样,对文档的任何修改都需要通过构建文档方式来测试。 你可以用两种方式来做: 建立你自己的暂存库与发布站点或在你本机上构建文档。下文会对这两种方式进行介绍:
根据以下步骤,你可以很容易的建立起自己的暂存库:
settings
Integration & services
Add service
下拉菜单,-fabric
以便于和你给其他项目创建的文档进行区分,例如: yourgithubid-fabric.readthedocs.io/en/latest
现在,只要当你在自己的分支上修改或增加文档内容,这个 URL 就会将这些内容自动更新!
以下是从 fabric-docs-i18n 主目录开始、不依赖于 ReadTheDocs、在本机上构建文档的简单步骤。 注意:你可能需要根据你的操作系统进行一些调整。
sudo pip install Sphinx
sudo pip install sphinx_rtd_theme
make html
以上步骤会在 build/html
目录下生成所有的html文件。你可以用浏览器在本地浏览。
当然,每次修改文档后你都需要重新执行 make html
。
另外,如果你愿意,你也可以通过以下命令(或你操作系统的类似命令)在本地运行一个 web 服务器:
sudo apt-get install apache2
cd build/html
sudo cp -r * /var/www/html/
然后你就可以通过 http://localhost/index.html
来访问这些 html 文件。
本文授权基于 知识共享 署名 4.0 国际协议。