互联网档案馆、古腾堡计划 和 Google 图书 是历史书籍的绝佳来源，但它们数字化工作的最终产品，虽然全面且功能齐全，但缺少最后一点润色。例如，我的兴趣之一是历史烹饪，特别是格鲁吉亚和摄政时期英国的烹饪以及美国烹饪的当代时期，但相关食谱的 PDF 版本通常只是基本的黑白扫描件，没有任何辅助查找或搜索的功能。纯文本版本虽然更易于搜索，但在美学上并不令人愉悦，并且经常包含大量 光学字符识别 错误。
我的个人项目之一是将我对历史烹饪的热爱与我对开源的热爱结合起来，利用开源文档工具制作精美的、基于网络的 18 世纪食谱版本。完成后，这些书籍将完全可搜索，并具有超链接的目录和索引。为了实现这一目标，我求助于 Sphinx 文档构建器，它为我提供了一种简单的方法来创建、组织和构建功能齐全的 HTML 书籍，而且只需很少的努力，并且额外的好处是，可以使用 Sphinx 轻松创建 PDF 和 EPUB 版本。
我正在转换的第一本书，汉娜·格拉斯的“简明易懂的烹饪艺术”，尚未完全准备好公开发布，但在本文中，我分享了我从工作中吸取的经验教训，以便其他人可以从我的工作流程中学习。可以把它看作是一个高度专业的 Sphinx 教程。我要描述的大部分内容对于从事开源文档工作的人来说是常识，但我希望通过分享我的过程，我将向具有中等计算机技能的非开源人士传授一种工具，他们可以使用该工具使与其爱好和兴趣相关的公共领域文本更加用户友好。诚然，Sphinx 确实需要对命令行有一定的熟悉程度，但我会解释复杂的部分。
安装 Python 和 Sphinx
Sphinx 是 Python 项目用来生成自身文档的工具，因此它是使用 Python 构建的。为了开始使用，您需要在您的系统上安装 Python。下载适用于您操作系统的 Python 3.x 安装程序，或者使用您的 Linux 发行版的软件包管理器安装 Python 3（例如，Fedora 上的 dnf install python3）。
安装 Python 时，如果您使用的是安装程序，请确保选中安装 pip 的选项，或者在为您的发行版安装 python3 软件包时安装相关的软件包。在 Fedora 上，该软件包名为 python3-pip。一旦您安装了 Python 和 pip，您就可以使用 pip 软件包管理器安装 Sphinx。在 Windows 上打开命令提示符，在 macOS 上打开终端，或在 Linux 上打开您选择的终端模拟器，然后键入：pip3 install -U sphinx。如果您看到错误消息，请以特权用户身份重新运行该命令，方法是在 Linux 和 macOS 上在命令前加上 sudo，或者在 Windows 上使用“以管理员身份运行”选项启动命令提示符。根据您的系统配置方式，系统可能会提示您输入管理员密码。
安装成功后，您将拥有开始使用 Sphinx 所需的一切。此外，还有 其他软件包 可以安装以提供更多选项。
设置新的 Sphinx 项目
要创建新的 Sphinx 项目，请打开命令提示符或终端，使用 cd 导航到您要存储项目的位置（例如，/home/USERNAME/Projects），然后运行 sphinx-quickstart 命令。快速入门将提示您提供有关您的项目的信息，并就各种配置选项做出选择。请注意，在 Windows 下，快速入门的提示将被乱码字符包围，但这无害，快速入门仍将正常运行。第一个提示“文档的根路径。”，允许您设置项目的位置。
如果您从要存储文件的目录运行 sphinx-quickstart 命令，您可以按键盘上的 Enter 键接受默认值。如果您想将您的项目存储在当前工作目录的子目录中，请在提示符处输入该子目录的名称，Sphinx 将创建该目录并将所有项目文件存储在该位置。
接下来，系统将提示您是否使用单独的“source”和“build”目录。默认值为否，这会将源文件放在项目的根目录中，而构建将最终出现在“_build”子目录中。选择默认值完全没问题，但如果您想将源文件和构建文件更分开，您可以选择是。这将把源文件放在“source”子目录中，而构建输出将进入“build”子目录。
第三个提示允许您更改“_static”和“_template”子目录的前缀。没有令人信服的理由从默认选项更改此设置。
接下来的两个提示是项目名称和作者姓名。项目名称可以是您正在转换的书籍的标题，但使用原书作者的姓名作为作者字段可能会导致一些奇怪之处，例如已故作者的姓名出现在页面页脚的版权信息中，紧挨着当年年份。如何最好地处理作者字段取决于您，但我将其设置为我的名字，并在项目文本中注明原作者。
然后，系统将提示您为项目分配版本号和发行号，在这种情况下，这没什么意义，但这是一个必填字段。随意将其设置为对您来说最有意义的任何内容。它可以设置为小于 1 的数字作为“beta”版本，并在您朝着完成的书籍迈进时递增到 1.0，或者您可以将版本和发行版设置为原书的出版年份，而不必担心更新它。
下一个设置，项目语言选项，应设置为书籍的原始语言。将语言选项设置为书籍最初出版的语言允许 Sphinx 在站点的标头中创建带有正确语言元数据的输出，并以正确的语言生成文本，例如“目录”和“快速搜索”。
对于大多数用户，接下来的两个提示应设置为默认值。两个提示中的第一个提示用户选择项目文件的文件扩展名。这默认为 .rst（对于 reStructuredText，Sphinx 使用的标记语言），因此没有理由更改它。第二个提示要求输入项目使用的主文件的名称。此文件是站点主页的内容和目录所在的位置。默认情况下，此文件名为“index.rst”，其中“index”部分来自在此提示符处输入的内容，而“.rst”扩展名来自上一个提示符。如果您确实想将其更改为“frontmatter”或其他名称，以便它不与将 index 名称用于书籍索引冲突，您可以这样做，但几乎没有理由这样做。
下一组提示都与 Sphinx 扩展有关。对于这样的项目，可以安全地对所有提示说“否”。唯一的例外是如果您计划使用 GitHub Pages 托管您完成的站点，那么您应该对“创建 .nojekyll 文件”提示说“是”。
最后，系统将询问您是否要创建 Make 文件和 Windows 命令行文件，这些文件可用于生成 HTML 输出，而无需运行 sphinx-build 并手动指定输入和输出目录。您应该对与您的系统相关的选项说“是”（macOS 和 Linux 的 Make 文件，或 Windows 的 Windows 命令行文件），或者如果您计划与使用不同操作系统的其他人协作，则对两者都说“是”。Linux 和 macOS 用户需要确保他们的系统上安装了 make，但 Windows 命令行文件无需安装任何额外的东西即可运行。
创建章节并添加内容
现在设置已完成，您可以暂时离开命令行，直到需要构建最终产品为止。所有内容创建和编辑都可以在文本编辑器中进行。GitHub 的 Atom 编辑器 是一个极佳的选择，但任何文本编辑器都可以工作，只要它可以保存纯文本文件。
首先在 Atom 或您选择的文本编辑器中打开项目的“index.rst”文件。您将在此文件中构建目录，列出将包含在书中的所有文件。这也是包含所有其他前言（例如您正在转换的书籍的扉页）的好地方。
您应该对“index.rst”进行的第一个编辑是删除“索引和表格”标题下方的“* :ref:`modindex`”行。对于此类项目，它完全是不必要的。然后，您可以修改“index.rst”的文本以适应您的项目需求。下面带有等号的行是标题，它们的文本可以更改为您想要的任何内容，以最适合您正在转换的书籍。例如，“欢迎来到 [您的项目名称] 的文档！”可以替换为书籍的实际标题。读取“内容：”的行可以更改或删除，任何最适合您的项目的内容（事实上，您可以添加任意数量的文本），只需确保保留“.. toctree::”和“:maxdepth: 2”行完整。
要构建目录并开始构建您的项目，您将在“:maxdepth: 2”行后留一个空行，并开始列出您将包含在书中的内容。您需要缩进列表，使其与“:maxdepth: 2”行中的初始冒号对齐，因此在文本开头前留三个空格。这些部分需要按顺序排列，因此“introduction”章节应在“chapter1”之前等等。这些行不应带有“.rst”文件扩展名，但是当您确实为不同的章节创建文件时，您将使用“index.rst”中列出的相同名称加上“.rst”扩展名保存它们。例如，您将在“index.rst”文件中有一行读取“chapter1”，但包含第 1 章内容的文件的文件名将为“chapter1.rst”。为了简单起见，将所有文件保存在与“index.rst”文件相同的目录中。
创建章节并用内容填充它涉及在您的文本编辑器中创建一个新文件，以您想要的任何方式添加书中的内容（手动转录、复制和粘贴 OCR 文本或任何最适合您的方式），并使用适当的文件名保存文件（例如，“chapter1.rst”用于在“index.rst”中列为“chapter1”的章节）。大部分工作来自正确格式化文本，考虑到 reStructuredText 相当简单的标记，这并不太费力或复杂。
在处理较旧的文本时，您需要了解的大部分内容是如何制作标题：一行文本下方的一系列 =，副标题：一行文本下方的一系列 -，粗体文本：文本左右两侧带有 **，以及斜体文本：文本左右两侧带有 *。需要注意的一件事是，目录是使用标题生成的，因此请务必在每个文件的开头至少包含一个标题（如果正在处理的书籍的章节没有文本标题，则可以是“第 X 章”，下面带有 = 号。）
更多 reStructuredText 格式选项可以在 reStructuredText 文档 中找到，如果您想使用更高级的格式。虽然 Sphinx 可以重现旧书中大多数的排版功能，但使用现代键盘输入“长 s”和各种连字非常耗时，因此您应该决定是否要包含它们。您可能想要追求真实性或选择简单性。
您会发现几乎不可能重现的一个功能是打印机的 页脚提示词，因为将书转换为 HTML 的最简单方法是基于章节，因此页码显然不会保留。如果您真的坚持保留页脚提示词，您可以进行劳动密集型工作，为每个单独的页面创建一个文件并以这种方式组织您的项目，但最终结果仍然不会完美。
重新创建书籍的索引
提取书籍的索引并重新创建它以创建超链接索引可能是此过程中最劳动密集的部分。您将通过阅读书籍的索引来逆向工程索引，找到章节的相关部分，无论是食谱还是其他类型的文本，并在适当的位置包含 Sphinx 的索引指令。要重新创建读取“牛肉，如何烤制”的索引条目，您将找到相关的食谱并在其后添加行“.. index:: Beef; How to roast”。然后，索引将包含一个“牛肉”主条目和一个“如何烤制”子条目，其中将包含指向相关食谱的链接。
构建网站
一旦您为正在转换的书籍的每个章节创建了文件，用所有原始内容填充了这些文件，并重新创建了索引，您就需要创建完成的 HTML。在所有这些辛勤工作之后，这是最简单的步骤。在命令行中，在您的项目根目录中，键入 make html。这将构建您的站点，并将最终产品放在“build”目录或“_build”目录中，具体取决于您在运行快速入门时是否选择分离源目录和构建目录（如果您分离了它们，则为“build”，如果您没有分离它们，则为“_build”。）还有更多构建选项，例如 EPUB 和 PDF。其中一些选项需要额外的软件，因此请查看 Sphinx 文档 以了解详细信息。在 Sphinx 的文档中，您还会找到有关大量高级设置和其他选项的信息，如果您想进一步调整您的最终项目，这些信息可能会有所帮助。
通过这些步骤，您已经赋予了旧书新的生命。
4 条评论