It is simple to build from a hierarchy of html files, it is downloadable, searchable, bookmarkable, has index, supports hyperlinks, can be opened on linux as well.
One downside of it is that recent Windows versions (=Windows 10) block the "execution" of this file if downloaded from "untrusted source" (=internet), so it needs a checkbox in file properties
to lift this "security block".
Afaik, NumPy used to ship docs in this format many years ago, but then dropped its support.
Indeed. It's much more niche than pdf, so I'd prefer to not consider it. You can easily build it locally though if you'd use it personally.
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.
I'm not so interested in the detailed discussion later on in this thread to be honest. Let me propose a simple solution that should make everyone happy:
1. We drop pdf builds in CI, the release process and the Docker image, but keep support in the code base.
2. Rohit volunteered to maintain the pdf build, so if he (or another person we know and trust to receive artifacts from and distribute them) wants to send PRs to fix doc build issues and merge a pdf build into
https://github.com/numpy/doc/, we'll review and merge those.
This keeps the pdf docs available for as long as someone does the work, while removing the burden from the release manager and general development. This seems like a decent compromise, similar to what we do for other things with a fairly niche audience.
Cheers,
Ralf