渲染文档站点

接下来的指南，介绍了如何将 pyDocusaurus 生成的文档文件合并入 Docusaurus 站点中。大致包含了以下要点：

创建一个新的 Docusaurus 站点；
使用 pyDocusaurus 生成文档相关的文件；
合并生成的文件；
针对已经存在的（例如分版）的文档站点，如何更新其中的内容。

1. 配备站点

使用以下命令，创建一个新的 Docusaurus 项目：

npx create-docusaurus@latest my-website classic --typescript --package-manager yarn

其后，进入项目目录，安装以下额外依赖项：

cd my-website
yarn add @docusaurus/plugin-content-docs @docusaurus/theme-common \
         @iconify-icons/codicon @iconify-icons/mdi @iconify-icons/octicon \
         @iconify/react docusaurus-plugin-sass sass sass-loader \
         prism-react-renderer remark-math@6 rehype-katex@7

yarn add --dev @types/node
yarn install
yarn dlx @yarnpkg/sdks vscode

2. 生成文档

前往你的 Python 模块包项目目录。假设你的项目具备如下文件结构：

运行 pyDocusaurus，

命令行
Python

python -m pydocusaurus render-doc my_package -o ./output_docs -u myname

convert_docs.py
from pydocusaurus import render_package_as_mdx
import my_package

if __name__ == "__main__":
    render_package_as_mdx(
        my_package, out_dir="./output_docs", package_info="myname"
    )

之后将会生成以下文件：

这些文件构成了一个可以直接复制入新 Docusaurus 站点的补丁：

# 将 pyDocusaurus 输出文件复制到站点中
cp -rf ./output_docs/* /path/to/my-website

3. 修改信息

接下来，可以修改：

docusaurus.config.ts: 包含站点元数据、主题、插件。
sidebars.ts: pyDocusaurus 已经生成了一个包含完整 API 结构的侧边栏。用户需要做的是定制侧边栏的其他部分，例如教程文档的侧边栏。

有可能还需要定制新的文档站点主页。以下内容可以作为一个参考范例：

pyDocusaurus 的主页配置

4. 更新现存的文档站点

在此情形下，不应该向已经存在的站点直接复制（覆盖）所有文件，这是因为有可能需要保留之前的 API 文档。

假设现在需要更新一个文档版本。建议按照以下步骤处理：

先按照官方指南执行，特别是要运行以下命令：
```
yarn docusaurus docs:version 1.0.0
```
使用 pyDocusaurus 渲染并输出文档文件。
删除文档站点项目中已经存在的 ./docs/apis 目录，因为当前的 API 文档将要全部委托给 pyDocusaurus。

复制新的 API 文档：

cp -rf output_docs/docs/apis ./docs/apis

合并新的侧边栏。

不可以替换掉整个sidebars.ts。

只应该更新属于 API 的部分：

const sidebars: SidebarsConfig = {
  // 默认情形下， Docusaurus 会按照 docs 文件夹结构自动生成侧边栏
  // tutorial: [{type: "autogenerated", dirName: "."}],

  tutorial: [
    "introduction",
    "tutorial/install",
    {...},
    "license",
  ],

  apis: [
    // 将你的新侧边栏配置复制到这里。
  ]
}

将新的 output_docs/src/env/variables.tsx 合并到你的站点项目中。需要增加的是以下部分:

interface EnvVariables {
  ...
  sourceVersion: {
    "main": string;
    "1.0.0": string;
    "2.0.0": string;  // 增加这一行
    [key: string]: any;
  }
  sourceURIs: {
    "main": {[key: string]: string};
    "v1.0.0": {[key: string]: string};
    "v2.0.0": {[key: string]: string};  // 增加这一行
    [key: string]: any;
  }
  ...
}

const variables: EnvVariables = {
  repoURL: "...",
  rawURL: "...",
  sourceVersion: {
    "main": "main",
    "1.0.0": "v1.0.0",
    "2.0.0": "v2.0.0",  // 这一行的值是 GitHub 上分支/tag的名字，也是sourceURIs所用的名字。
  },
  sourceURIs: {
    "v2.0.0": {
      // 将新生成的 sourceURIs.main 内容复制到这里。
    }
    "v1.0.0": {
      ".": "./__init__.py",
      ...
    },
    "main": {
      ".": "./__init__.py",
      ...
    }
  },
};

这一步会将你的项目中每个实体对应的源代码行号，告知给动态渲染机制。据此会自动在 API 文档页面顶端的导航条，生成通往你源码的链接。

1. 配备站点​

2. 生成文档​

3. 修改信息​

4. 更新现存的文档站点​

1. 配备站点

2. 生成文档

3. 修改信息

4. 更新现存的文档站点