將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>