npm 包 gatsby-sphinx 使用教程

gatsby-sphinx 是一个方便在 GatsbyJS 网站中使用 Sphinx 文档的插件。在这篇文章中，我们将深入学习如何使用 gatsby-sphinx 在我们的 GatsbyJS 网站中加入 Sphinx 文档。

环境准备

在开始使用 gatsby-sphinx 之前，确保你已经安装好以下软件：

• Node.js
• GatsbyJS
• Python
• Sphinx

安装

gatsby-sphinx 包可以通过 npm 安装：

npm install gatsby-sphinx

配置

在你的 GatsbyJS 网站中创建一个 gatsby-config.js 文件并添加以下内容：

-- -------------------- ---- -------
-------------- - -
  -------- -
    -
      -------- ----------------
      -------- -
        ----- --------
        ------- ----------------------
        -- -- ------ --- ---- ------------- ---- ------- ------ -------- ----------- --- ---- ------
        ---------- ------
      --
    --
  --
-

在上面的配置中，我们指定了以下选项：

• path: 网站中 Docs 页面的 URL 路径。
• config: Sphinx 项目的配置文件路径。在此配置中，我们使用了 docs/source/conf.py。这取决于你的 Sphinx 项目的具体结构。
• buildHtml（可选）: 如果 Sphinx 生成的 HTML 已被构建，并且你已经把这些 HTML 文件存放在你的 Gatsby 网站中，那么设置 buildHtml 选项为 True 将会加速渲染。

示例代码

我们现在已经配置好了 gatsby-sphinx，现在我们来介绍如何在网站中加入 Sphinx 文档。

1. 修改 Sphinx 配置文件

打开您的 Sphinx 项目的 conf.py 配置文件，添加以下内容：

# 添加这一行以便生成 React 静态页面
html_context = {"react": True}

此配置将使用 React 重新渲染 Sphinx 的 HTML 页面。

2. 在文档中添加相应的 HTML 标记

为了使 gatsby-sphinx 正常工作，您需要在您的 Sphinx 文档中添加 HTML 元素。

.. raw:: html

  <div data-interactive>
     :jsx:`<h1>Hello World!</h1>`
  </div>

这里的 data-interactive 元素声明了这里是需要使用 React 重新渲染的 HTML 元素。接着使用 :jsx: 来渲染 React 组件。

3. 运行 GatsbyJS 网站

最后，运行 GatsbyJS 网站：

gatsby develop

这样，您的 Sphinx 文档就会被成功集成到 GatsbyJS 网站中。

总结

通过 gatsby-sphinx，我们可以很方便的在 GatsbyJS 网站中使用 Sphinx 文档。这对于需要展示文档的网站使用，将是一款非常实用的插件。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600668fad9381d61a354100e