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