Skip to main content

One post tagged with "方案"

View All Tags

· 9 min read
成峰

文档系统需求​

一体化平台使用文档编写有一定的技术门槛，需要开发人员共同努力完成文档的编写和维护，一个开发人员对文档平台的需求应该包括以下几个方面：

  1. 易用性：文档平台应该易于使用和上手，能够让开发人员快速创建、编辑和发布文档，避免复杂的配置和操作。
  2. 多语言支持：随着全球化的趋势，开发人员需要将文档翻译成多种语言，因此文档平台应该支持多语言文档的创建和管理，同时也要支持多种语言的搜索和导航。
  3. 多种文档格式支持：开发人员使用多种格式编写文档，如Markdown、reStructuredText等，文档平台应该支持这些格式的导入和导出。
  4. 版本控制：文档随着软件的迭代而不断更新，因此文档平台应该支持版本控制，可以让开发人员回溯文档的历史版本，也可以协同编辑和审核文档。
  5. 搜索和导航：文档平台应该具备良好的搜索和导航功能，可以让开发人员快速查找和访问所需的文档，提高效率。
  6. 主题和样式：文档平台应该支持自定义主题和样式，可以让开发人员将文档与品牌和网站风格保持一致。
  7. 插件和扩展：文档平台应该提供丰富的插件和扩展机制，可以让开发人员轻松地添加各种功能和定制化需求。

综上所述，文档平台应该满足开发人员的需求，让他们能够更加高效地创建、编辑和管理文档，同时提供良好的搜索和导航功能，让用户能够快速找到所需的信息。

开源文档工具选型​

主流开源文档工具​

以下是开发人员常用的流行的开源文档工具：

  1. GitBook：GitBook是一种开源文档编写和托管平台，它可以让你使用Markdown格式编写文档，并将其发布到GitBook上。
  2. Sphinx：Sphinx是一种基于Python的文档生成工具，它可以使用reStructuredText语言编写文档，并支持多种输出格式，如HTML、PDF、EPUB等。
  3. Jekyll：Jekyll是一种静态网站生成器，它使用Markdown和Liquid模板语言编写文档，并可以将文档生成为HTML格式，可以很好地用于生成静态网站。
  4. MkDocs：MkDocs是一种使用Markdown格式编写文档并将其转换为静态网站的工具，它提供了许多主题和插件，使得文档可以轻松地进行自定义。
  5. Read the Docs：Read the Docs是一种在线文档托管平台，它支持使用多种格式编写文档，并提供了自动构建和部署的功能。
  6. Docusaurus：Docusaurus是一个由Facebook开发的静态网站生成器，它专门用于构建开源软件的文档网站，并提供了许多主题和插件。
  7. Doxygen：Doxygen是一种用于生成C++、Java和Python等语言文档的工具，它可以从源代码中提取注释和文档，并生成HTML、PDF等多种格式的文档。

以上这些工具都是非常流行的开源文档工具，开发人员可以根据自己的需求和喜好选择适合自己的工具来编写和管理文档。

选择文档方案​

基于Docusaurus构建云原生一体机的文档系统，选择Docusaurus的理由：

  1. 更灵活的主题支持：Docusaurus v2提供了更灵活的主题支持，使您可以更轻松地自定义您的文档网站的外观和感觉。您可以根据自己的需要添加和修改主题组件。
  2. 现代化的技术栈：Docusaurus使用了现代化的技术栈，包括React、Webpack和Babel。这些技术使您可以更轻松地开发和维护您的文档网站，并使其与现代Web应用程序的开发方式保持一致。
  3. 更好的性能：Docusaurus v2的性能比早期版本更好。它使用了现代化的构建工具，并具有更好的缓存策略，因此加载速度更快。
  4. 改进的搜索功能：Docusaurus v2的搜索功能比早期版本更好。它使用了现代化的搜索引擎，可以更准确地匹配搜索查询，并支持中文搜索。
  5. 更易于使用的插件系统：Docusaurus v2的插件系统更易于使用，并支持更多的插件。这些插件可以使您更轻松地添加各种功能，如社交分享按钮等。
  6. Facebook开发，社区活跃，我们也进行了一些预研。

文档开发指引​

以下是在基于Docusaurus v2构建的文档管理系统上开发文档的一些指引：

  1. 安装Docusaurus

首先，您需要在本地计算机上安装Node.js和npm。然后，您可以使用npm在全局范围内安装Docusaurus：

npm install --global docusaurus-init
  1. 验证本地环境

使用以下命令在您的项目目录中初始化Docusaurus：

docusaurus-init

根据提示输入项目名称，选择您要使用的Yarn或npm包管理器，选择要使用的默认模板，等等。一旦完成，Docusaurus将在您的项目目录中创建一个新的文件夹。

  1. 编辑文档

在Docusaurus中，文档位于“docs”文件夹中。您可以在该文件夹中创建子文件夹以组织您的文档。每个子文件夹都应该包含一个名为“README.md”的Markdown文件。您可以使用Markdown语法编写文档。

  1. 编辑网站配置

您可以编辑位于“website”文件夹中的“docusaurus.config.js”文件来配置您的Docusaurus网站。该文件包含诸如网站名称，主题，插件，网站描述等选项。

  1. 预览和构建网站

使用以下命令在本地计算机上预览您的Docusaurus网站：

npm run start

您可以在浏览器中访问“http：// localhost：3000”来查看网站。

要构建静态网站文件，请使用以下命令：

npm run build

网站文件将生成在“build”文件夹中，您可以将其上传到托管网站上。

这些是使用Docusaurus开发文档的基本步骤。您可以使用Docusaurus的许多其他功能来优化您的文档，例如搜索，部署到GitHub Pages等。请查看Docusaurus文档以获取更多信息。