Sphinx Readthedocs 主题字体-真棒集成答案

【问题标题】：Sphinx Readthedocs theme Font-awesome integrationSphinx Readthedocs 主题字体-真棒集成
【发布时间】：2016-06-23 10:59:35
【问题描述】：

我知道这可能是一个非常愚蠢的问题，但我没有设法在网上找到任何关于潜在解决方案的信息。

我正在使用 Sphinx 1.4 和 sphinx_rtd_theme 为我的 Django 项目生成一些文档。我一直在尝试找到一种在 .rst 文件中使用字体真棒图标的方法，但没有找到方法。我查看了 sphinx_rtd_theme 源文件，并且 fa-* 图标包含在 theme.css 文件中。但是，我不知道实际上包含它们的方法。

它是指令、解释文本还是类似的东西？我已经尝试过 icon、fonticon 和 fa 作为上述任何一种方法，但都没有奏效。

任何帮助将不胜感激。

我知道我可能会使用原始 HTML，但我想尽可能避免这种情况。

【问题讨论】：

您是否尝试过查看例如anil.io/cheatsheets/sphinx/…?截至 1 月，如果您没有任何额外的插件，apparently、raw:: html 是您的最佳选择。
您好，我曾尝试过 :fa: 以前（刚才又试了一次，从您发送给我的参考资料中复制并粘贴）但我收到与以前相同的错误：docs/source/manual/menus/mainmenu.rst:55: ERROR: Unknown interpreted text role "fa". EDIT ：对不起，我现在才意识到它是一个外部库。我再看看。
那我猜这只是在你使用 Bootstrap RST 的情况下。
@jonrsharpe 看起来你是对的。在这种情况下，我将开始使用 raw 指令。感谢您提供额外的参考。

标签： django font-awesome python-sphinx read-the-docs

【解决方案1】：

可以使用Sphinx的rst-class指令，如下：

.. rst-class:: fa fa-fontawesome

   the font awsome flag will be attached to this paragraph

rst-class 将为指定的下一个元素设置类属性。

以下代码仅呈现图标：

.. rst-class:: fa fa-font-awesome

   |

当然，您也可以使用自定义类来进一步设置元素的样式。

【讨论】：

这很好用，正是我想要的。我还希望从相同的 .rst 文件中生成 .pdf ，并且它们不会为图标呈现，但我可能可以解决这个问题。不过对 .html 文件非常有用！

【解决方案2】：

你也可以使用https://sphinx-panels.readthedocs.io/en/latest/#inline-icons:

:fa:`bars`
:fa:`spinner,text-white bg-primary fa-2x,style=fa`

【讨论】：

它可以工作，但为此您需要安装 sphinx-panels：pip install sphinx-panels。 (pypi.org/project/sphinx-panels)。并将其添加到您的 conf.py：extensions = ['sphinx_panels']

【解决方案3】：

我刚刚学习 Sphinx 并且有同样的问题，但使用原始 HTML 对我来说很好。也许这个解决方案会对那里的人有所帮助......

在 conf.py 文件中，添加指向您的 Fontawesome 套件代码 URL 的链接

html_js_files = [
    'https://kit.fontawesome.com/##########.js',
]

然后，在 Sphinx 中使用带有原始 HTML 指令的 fontawesome 图标

.. |fa-fort-awesome| raw:: html

   <i class="fab fa-fort-awesome"></i>

Here is some text |fa-fort-awesome| with the icon in the middle.

这是它呈现为 HTML 的方式...

【讨论】：

【解决方案4】：

为了使图标在 HTML 和 Latex 上可用，请从 https://fontawesome.com/download 下载 FontAwesome Web Package，将 font-awesome/svgs/solid 包含到您的项目 _static 文件夹中，并使用如下图像指令：

The |fa-bars| function is to toggle the left Sidebar Menu between being collapsed behind the button or displayed on the screen.

.. |fa-bars| image:: _static/font-awesome/svgs/solid/bars.svg
:width: 20px
:alt: hamburguer button

结果：

<link href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet"/>
The <i class="fa fa-bars"></i> function is to toggle the left Sidebar Menu between being collapsed behind the button or displayed on the screen.

【讨论】：