3

这是一个非常奇怪的问题：

我已经能够使用 Sphinx 生成 html 和 pdf 输出；而且我必须将它们与我的发行版捆绑在一起（到 PyPI），以便用户可以访问它们。

虽然我可以直接上传 HTML 文档以托管在 PyPI 上，但我也无法上传它的 PDF LaTeX 版本。我想这样做是因为实际代码低于 50K，但是将文档与它捆绑在一起会使它膨胀到大约 300K。

最终，我希望用户能够拥有文档的离线版本，而无需下载几页 sphinx 文档。

所以我的问题是：我是否可以自动将 PDF 与 HTML 捆绑在一起，以便最终用户可以直接下载 PDF 以供离线使用？（我意识到我可以将 PDF 与我的发行版捆绑在一起，但这似乎是一种更简洁的方法）

4

3 回答 3

3

我修改了 Reinout van Rees 的解决方案：

我创建了一个downloadMe.rst（其中包含 lorem ipsum 文本），它在make html运行时自动内置到 HTML 中，因此downloadMe.html使用 lorem ipsum 文本。

然后我编辑了 Makefile 的 html 目标，如下所示：

  1. 让它构建 LaTeX pdf 并将其复制到_build/html/static.
  2. 使用sed脚本将 lorem ipsum 文本替换为downloadMe.html指向 PDF 中的 HTML 超链接_build/html/_static。

当所有这些都完成后，这就是 html 目标的Makefile样子：

html:
        @echo "Making LaTeX"
        make latex
        ( cd _build/latex/; make ) # the LaTeX needs to be built separately. This can be done in a subshell
        @echo "Done making LaTeX"
        @echo "Copying PDF to Static"
        cp _build/latex/Genetic.pdf _build/html/_static/
        @echo "Copy PDF to Static... DONE"
        @echo "Adding PDF to HTML"
        sed -i '' 's/lorem\ ipsum/\<a href="_static\/Genetic.pdf"\>Download\ Me\<\/a\>/g' _build/html/downloadPDF.html
        @echo "Done adding PDF to HTML"
        @echo "Removing LaTeX dir"
        rm -rf _build/latex
        @echo "Done removing LaTeX dir"

        $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
        @echo
        @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

这个 makefile 目标，虽然有点重，但它的优点是即发即弃；我只需要make html一次性完成所有文档，完成后我不必编辑任何文件make。这让我在上传到 PyPI 之前忘记编辑某些文件或其他文件以正确制作文档的空间更少

于 2012-11-19T16:56:10.463 回答
2

另一种选择（也是我的其他答案）是让http://readthedocs.org构建和托管您的文档。他们还可以构建 PDF，因此您可以在文档和/或README.rst.

例如，请查看https://readthedocs.org/projects/zestreleaser/downloads/。您会在此处看到 PDF、epub 和压缩 html 下载的链接。可能正是你想要的。

于 2012-11-19T10:57:12.013 回答
1

您可以修改Makefile放置在您doc/build/目录中的 Sphinx。在latexpdf目标的末尾，添加一行以将 PDF 复制到 html 构建目录。这是一个例子（我只添加了最后一行）：

latexpdf:
    $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    @echo "Running LaTeX files through pdflatex..."
    $(MAKE) -C $(BUILDDIR)/latex all-pdf
    @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
    cp $(BUILDDIR)/latex/*pdf $(BUILDDIR)/html/

然后，您可以在README.rst.

（如果 README 包含在您的 Sphinx 中，这可能会给您一个 Sphinx 警告，因为缺少目标文件。除非您还将 PDF 复制到源目录。但是您有复制旧版本的风险。 )

我的建议：在您的 中添加“原始 html”条目README.rst，它还具有不显示在 PDF 输出中的优点 :-)

.. raw:: html

    <a href="pypi/link/to/pdf">PDF version</a>
于 2012-11-19T10:49:31.733 回答