If it's any help, I would suggest looking at how SymPy does its PDF documentation. We have a few adjustments to the Sphinx defaults to make things work (although it's honestly not that much, mainly just using XeTeX for Unicode support). https://github.com/sympy/sympy/blob/master/doc/Makefile
One of the things that was mentioned in the issue is SVG images. We found in SymPy that the best way to convert SVG images to a format that can be used for PDFs is to use Google Chrome (all the other SVG to PDF converters are flawed in some way, see https://github.com/sympy/sympy/pull/22468 for details). See this script https://github.com/sympy/sympy/blob/master/doc/convert-svg-to-pdf.sh and also this PR https://github.com/sympy/sympy/pull/23035. Perhaps the code in that PR should be factored out into a separate Sphinx extension that can be reused by other projects. I personally don't use PDF documentation but I know for SymPy, many people do, which is why we have continued to support it. Also, one final thing I will note is that if you have any LaTeX math in your documentation, the PDF build is the only way you can be sure that that LaTeX is valid. MathJax only renders the LaTeX in the browser when the page is loaded so you will only notice invalid math once you look at it and see it gives an error. To contrast, the PDF docs fail at the build stage if the LaTeX is invalid. Obviously we have a lot of math in the SymPy docs but I don't know if there is any in the NumPy or SciPy docs. This does also mean that to be useful you actually need to build it on CI. If you don't, you will end up with docs that don't actually build any more by the release because of unseen errors (even without LaTeX math this will likely end up happening, so I would recommend against this). Aaron Meurer On Sun, May 22, 2022 at 2:08 PM Charles R Harris <charlesr.har...@gmail.com> wrote: > Hi All, > > This is a proposal to drop the generation of pdf documentation and only > generate the html version. This is a one way change due to the difficulty > maintaining/fixing the pdf versions. See minimal discussion here > <https://github.com/numpy/numpy/issues/21557#issuecomment-1133920412>. > > Chuck > _______________________________________________ > NumPy-Discussion mailing list -- numpy-discussion@python.org > To unsubscribe send an email to numpy-discussion-le...@python.org > https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ > Member address: asmeu...@gmail.com >
_______________________________________________ NumPy-Discussion mailing list -- numpy-discussion@python.org To unsubscribe send an email to numpy-discussion-le...@python.org https://mail.python.org/mailman3/lists/numpy-discussion.python.org/ Member address: arch...@mail-archive.com
