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

Question

This is a really weird question:

I have been able to generate html and pdf output using Sphinx; and I had to bundle both with my distribution (to PyPI) so that both would be accessible to the user.

Though I can upload HTML documentation directly to be hosted on PyPI, I am unable to upload the PDF LaTeX version of it as well. I want to do this because the actual code is under 50K, but bundling the documentation with it bloats it up to about 300K.

Ultimately, I would like the user to be able to have an off-line version of the documentation without having to download several pages of sphinx documentation.

So my question is this: is it possible for me to automatically bundle the PDF with the HTML so that an end user can directly download the PDF for off-line use? (I realize that I can bundle just the PDF with my distribution, but this seems a cleaner approach)

Answer 1

I went with a modification of Reinout van Rees's solution:

I created a downloadMe.rst (which has lorem ipsum text within it) which gets automatically built into HTML when make html is run and therefore makes downloadMe.html with the lorem ipsum text.

I then edited the Makefile's html target as follows:

1. make it build the LaTeX pdf and copy it over into _build/html/static .
2. use a sed script to replace the lorem ipsum text in downloadMe.html with an HTML hyperlink to the PDF in _build/html/_static .

When all of that was done, this is what the html target in Makefile looks like:

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."

This makefile target, though a little heavier has the advantage that it's fire-and-forget; I just have to make html and all the documentation is done in one go and I don't have to edit any files when make is done. This leaves less room for me to forget to edit some file or other to make the documentation correctly before uploading to PyPI

Answer 2

An alternative (also to my other answer) is to let http://readthedocs.org build and host your documentation. They can also build PDFs, so you can provide a link to the PDF (build and hosted by readthedocs) in your documentation and/or your README.rst .

For an example, look at https://readthedocs.org/projects/zestreleaser/downloads/ . You see links there for a PDF, an epub and a zipped html download. Could be exactly what you want.

Answer 3

You could modify the Makefile that Sphinx placed in your doc/build/ directory. At the end of the latexpdf target, add a line to copy the PDF to the html build dir. Here's an example (I only added the last line):

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/

You can then add a link to the PDF in your README.rst .

(If the README is included in your Sphinx, this probably gives you a Sphinx warning, though, for a missing target file. Unless you also copy the PDF to your source dir. But then you have the risk of an older version being copied.)

My suggestion: add a "raw html" entry to your README.rst , it also has the advantage of not showing up in the PDF output :-)

.. raw:: html

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