将Sphinx PDF输出附加到Sphinx HTML输出

Question

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

我已经能够使用Sphinx生成html和pdf输出; 而且我不得不将两者都捆绑到我的发行版（到PyPI），这样两者都可以被用户访问。

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

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

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

Answer 1

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

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

然后我按如下方式编辑了Makefile的html目标：

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

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

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之前忘记编辑某个文件或其他文件以便正确编写文档的空间更小

Answer 2

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

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

Answer 3

您可以修改Sphinx放在doc/build/目录中的Makefile 。 在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添加指向PDF的链接。

（如果您的Sphinx中包含自述文件，这可能会为您提供Sphinx警告，但是对于丢失的目标文件。除非您还将PDF复制到源目录。但是您可能会有复制旧版本的风险。 ）

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

.. raw:: html

    <a href="pypi/link/to/pdf">PDF version</a>