Swift-DocC-Render

Swift-DocC-Render 是一个由 Vue.js 驱动的网页单页应用程序（SPA），用于创建丰富的代码文档网站。页面和内容是使用 DocC 的渲染 JSON 数据生成的。它具有适合文档网站的设计。

SPA 是完全在浏览器中使用 JavaScript 在运行时动态渲染的网页应用程序。

Swift-DocC 是一个用于构建和预览文档的工具，旨在简化从框架和软件包生成参考文档的过程，以及创建以 Markdown 编写的自由格式文章和教程。它生成一个文档存档格式的文件夹（扩展名为 .doccarchive），其中包含文档的机器可读 JSON 数据输出，Swift-DocC-Render 使用这些数据来生成渲染后的文档。

入门指南

注意：需要 Node.js v18 和 npm v9.5。一个简单的设置方法是安装 nvm，然后在 Swift-DocC-Render 仓库中运行 nvm install。要将这些版本设为默认，请在安装命令中添加 --default。

1. 下载此仓库并进入其文件夹

   git clone https://github.com/apple/swift-docc-render.git
   cd swift-docc-render

2. 安装依赖项

   npm install

3. 在 localhost:8080 运行具有热重载功能的本地服务器

   在本地开发时，你可能想要设置代理来处理数据请求。可以通过设置 VUE_APP_DEV_SERVER_PROXY 环境变量来指向磁盘上的文档存档（.doccarchive 或 .docc-build）或 HTTP 端点：

   VUE_APP_DEV_SERVER_PROXY=[文档存档路径] npm run serve

   或者，你可以在项目根目录创建一个 .env.development.local 文件，添加 VUE_APP_DEV_SERVER_PROXY 环境变量，这样就不必每次在 npm run serve 脚本中设置它。

使用 Swift-DocC-Render 渲染文档

按照这些步骤生成文档存档，设置渲染器路径，并使用 Swift-DocC-Render 在本地渲染你的文档。

渲染和构建文档

你需要安装 DocC 才能预览和构建文档。阅读 Swift 入门指南 了解更多信息。

要预览文档，运行 npm run docs:preview。这将在 http://localhost:8000/documentation/swiftdoccrender 启动预览服务器。

要构建文档，运行 npm run docs:build。

错误报告和功能请求

提交错误报告

Swift-DocC-Render 使用 GitHub 跟踪所有错误报告。 提交错误报告时，我们要求你遵循 Swift 的错误报告指南 并提供尽可能多的细节。

如果你能确认该错误在使用 main 分支的最新提交的 Swift-DocC 时出现 （参见构建 Swift-DocC-Render）， 这将有助于我们更快地追踪错误。

提交功能请求

对于功能请求，请随时在 GitHub 上创建一个 New Feature 类型的 issue， 或在 Swift 论坛上发起讨论。

如果你看到 Swift-DocC-Render 可以改进以更好地满足你的需求，请不要犹豫，提交功能请求。

所有面向用户的功能必须在 Swift 论坛 中讨论，然后才能默认启用。

为 DocC 做贡献

请查看贡献指南了解更多信息。

<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->