Question

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

我已经能够使用Sphinx生成html和pdf输出;我不得不将两者都与我的distribution (to 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目标：

使其构建LaTeX pdf并将其复制到_build/html/static。
使用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放在Makefile目录中的doc/build/。在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>

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

3 个答案: