As the person initiated the PDF drop in SciPy, I'd give my reasoning for why it bugged me in the first place

- The typography is \subsubpar (as a TeX person should say) and just an eyesore, this actually matters a lot more than you would assume and unreadable in mobile without constant zooming because of nonresponsive format
- Almost all links are broken and left as double backticks since it is not originally designed for PDF navigation
- Code copy/pasting is broken (due to how the TeX package for listings setup) regardless of the PDF viewer
- It is mostly empty space hence bloats the page number because it comes from the HTML format and not the other way around as say, TeX4ht workflow would follow.
- It is an absolute waste of resources on CI/CD since it fires up per Pull Request (maybe we can argue to reduce it to per main-branch-merge but doesn't change the fact that it is just wasteful and burdensome)
- Like Ralf mentioned the infrastructure for a TeX run is unacceptable for today's standards (but it is the LaTeX maintainers to blame for it and I know some of them, they know this very well and trying hard to reduce it)
- It is a very unstable workflow and errors out depending on the planets alignment because, again, it is coming from an awkward Markdown source which is not designed for. Becomes very annoying for maintainers to see it fail for otherwise a perfectly valid code.

The API reference PDF (7.2 mb) is also difficult to find compared to the front page version which is the User guide (3.x mb). So probably there is no demand for it anyways because it didn't cause too much noise as far as I know.







On Mon, May 23, 2022 at 8:34 AM Ralf Gommers <ralf.gommers@gmail.com> wrote:


On Mon, May 23, 2022 at 6:51 AM Matti Picus <matti.picus@gmail.com> wrote:

On 23/5/22 01:51, Rohit Goswami wrote:
>
> Being very hard to read should not be reason enough to stop generating
> them. In places with little to no internet connectivity often the PDF
> documentation is invaluable.
>
> I personally use the PDF documentation both on my phone and e-reader
> when I travel simply because it is more accessible and has better
> search capabilities.
>
> It is true that SciPy has removed them, but that doesn't necessarily
> mean we need to follow suit. Especially relevant (IMO) is that large
> parts of the NumPy documentation still make sense when read
> sequentially (going back to when it was at some point partially kanged
> from Travis' book).
>
> I'd be happy to spend time (and plan to) working on fixing concrete
> issues other than straw-man and subjective arguments.
>
> Personally I'd like to see the NumPy documentation have PDFs in a
> fashion where each page / chapter can be downloaded individually.
>
> -- Rohit
>
> P.S.: If we have CI timeout issues, for the PDF docs we could also
> have a dedicated repo and only build for releases.
>
> P.P.S: FWIW the Python docs are also still distributed in PDF form.
>
> On 22 May 2022, at 21:41, Stephan Hoyer wrote:
>
>     +1 let’s drop the PDF docs. They are already very hard to read.
>
>     On Sun, May 22, 2022 at 1:06 PM Charles R Harris
>     <charlesr.harris@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
>

Thanks Rohit for the offer to take on this project.

I don't think we should block the release on the existence of PDF
documentation. It is a "nice to have", not a hard requirement.


One strategy to discover problems with the PDF builds in CI would be to
add a weekly build of PDF.

That would just mean more CI maintenance/breakage, that the same folks who always take care of CI issues inevitably are going to have to look at.

I'm +1 for removing pdf builds, they are not worth the maintainer effort - we shouldn't put them in CI, and they break at release time too often. It will remain possible for interested users to rebuild the docs themselves - and we can/will accept patches for docstring issues that trip up the pdf but not the html build. That's the same support level we have for other things that we do not run in CI.

When we removed the SciPy pdf docs, the one concern was that there was no longer an offline option (by Juan, a very knowledgeable user and occasional contributor). So I suspect that most of the pdf downloads are for users who want that offline option, but we don't tell them that html+zip is the preferred one.

Another benefit of removal is to slim down our dev Docker images a lot - right now the numpy-dev image is 300 MB larger than the scipy-dev one because of the inclusion of TeX Live.

Cheers,
Ralf

_______________________________________________
NumPy-Discussion mailing list -- numpy-discussion@python.org
To unsubscribe send an email to numpy-discussion-leave@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: ilhanpolat@gmail.com