为DevStream创建文档

背景

  1. 我们使用readthedocs托管文档,不过你并不需要对readthedocs了解很多,即可为DevStream的文档做出贡献。
  2. Readthedocs支持sphinxmkdocs来构建文档站点;我们选择了mkdocs。如果你遇到任何问题,请参阅mkdocs的官方文档
  3. 我们使用了mkdocsmaterial主题。有关material主题的更多信息请参见:
  4. 我们还使用了mkdocs的两个插件:

前置条件

  • Python3(mkdocs是基于Python的)
  • pip3(安装依赖项)

建议macOS用户进行如下操作:

文档根目录

mkdocs的根文件夹位于/

主配置是根目录/下的mkdocs.yml,docs文件夹是/docs

i18n(国际化)

目前,我们支持两种语言:

  • 英文
  • 简体中文

值得注意的是,搜索功能不适用于简体中文(mkdocs搜索功能的限制)。

对于每个英文文档,在单独的文件中都有中文翻译。 如果英文文档的文件名是doc_name.md,那么应该还有一个名为doc_name.zh.md的文件。要创建中文文档,请将中文翻译内容放入doc_name.zh.md。该文件是doc_name.md(英文)的翻译。

创建一个新文档

要创建新文档,请执行以下操作:

  • /docs文件夹中创建doc_name.mddoc_name.zh.md。如有必要,你可以将它们放在恰当的子文件夹下。参考当前目录结构来确定适合该文档的最佳路径。
  • 编写文档的内容。你可以选择只写英文文档或中文文档;你不必用两种语言编写文档;当然如果你希望展示你中英双语的实力的话,我们建议你两种语言的文档同时编写,一并提交。
  • 大多数情况下,你不需要考虑导航菜单,它是整个文档网站的目录。但是如果需要自定义导航菜单,可以参考设置导航

设置导航

如果要自定义导航菜单,可以更新mkdocs.yaml中的nav:部分,支持通配符和子目录链接。例如:

Text Only

  1. nav:
  2. - DTM Commands Explained in Depth:
  3. - commands/autocomplete*.md
  4. - commands/*.md
  5. - Plugins:
  6. - plugins/plugins-list*.md
  7. - plugins/*.md
  8. - Best Practices: best-practices/
  9. - 'contributing_guide*.md'
  10. - 'contributor_ladder*.md'
  • 通常,contributing_guide*.md指代了contributing_guide.mdcontributing_guide.zh.md两个文件,分别是英文和中文文档;
  • 如果在commands/, plugins/, best-practices/目录中创建文档,不需要更新nav

如果想了解更多关于导航的配置,请参阅配置页面与导航导航语法

在本地查看你的更改

运行:

Bash

  1. # 在repo的根目录下
  2. pip3 install -r docs/requirements.txt
  3. mkdocs serve

请在提交PR之前在本地确认你的更改。

推荐的工具和阅读材料