pdf - ReadTheDocs 在没有我的 HTML 表格的情况下生成 PDF

Question

我们正在转换一个相当大的文档以在 ReadTheDocs 上托管。我们对 Markdown 表格语法所支持的简单表示并不满意，因此我们将表格编码为 HTML。在 HTML 查看器中非常好（例如， http: //manual.cytoscape.org/en/latest/Command_Line_Arguments.html的结尾）。

在 ReadTheDocs 生成的 PDF 版本中，我们的每个表格都完全丢失（参见https://media.readthedocs.org/pdf/cytoscape-working-copy/latest/cytoscape-working-copy.pdf上的第 9 页）。

我们将表格编码为 HTML 是否犯了错误？我们是否可以采取不同的方式并在 HTML和PDF 中获得漂亮的表格？

任何意见将是有益的 ...

谢谢！

Answer 1

我自己没有使用 ReadTheDocs，但是通过阅读他们的入门指南，我假设您使用的是 Sphinx？虽然 Markdown 支持嵌入原始 HTML，但 Sphinx 不支持将其转换为其他格式。

您应该考虑改用 reStructuredText（Sphinx 的原生标记格式），因为它比 Markdown 先进得多。如果您需要，它甚至可以使用自定义指令和角色进行扩展。但请务必先检查reStructuredText 表是否提供您所需的灵活性。Pandoc可以将您的 Markdown 文件转换为 reStructuredText。

我看到您正在使用表格来记录命令行选项。reStructuredText 支持使用选项列表记录命令行选项。理论上，您可以更改选项列表在输出文档中的表示方式，但这可能并不容易实现，尤其是对于使用 LaTeX 的 PDF 输出（无耻的插件：使用rinohtype进行 PDF 输出应该会在未来变得更容易）。