[Numpy-discussion] Dropping the pdf documentation.

[Charles R Harris]

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
.

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: arch...@mail-archive.com

[Numpy-discussion] Re: Dropping the pdf documentation.

[Stephan Hoyer]

+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 
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
> .
>
> 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: sho...@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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Rohit Goswami]

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 


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
 
.


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: sho...@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: rgosw...@quansight.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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Stephan Hoyer]

On Sun, May 22, 2022 at 3:52 PM 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.
>
The HTML docs can also be downloaded for offline use.

Perhaps someone has access to analytics from numpy.org that can tell us how
often the PDF docs are viewed? I believe PDFs could be more convenient for
some use-cases, but I don't think it's worth the trouble of the separate
rendering pipeline for a relatively niche use-case.
___
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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Rohit Goswami]

The HTML docs can also be downloaded for offline use.


HTML documentation isn't easy to navigate on anything other than a 
laptop / tablet. It also makes it confusing when there isn't an internet 
connection because of the external links. Also it is hard (subjectively) 
to read in order.


Also more subjective points:
- A PDF can be annotated
- A PDF can be bookmarked
- A PDF has a separate reading app / device from browsing
- A PDF can be printed out (yes sometimes this might still be useful)


Perhaps someone has access to analytics from 
[numpy.org](http://numpy.org) that can tell us how often the PDF docs 
are viewed?


It would be interesting to see the comparison between the downloads of 
the offline HTML documentation and the PDF documentation.


I don't think it's worth the trouble of the separate rendering 
pipeline for a relatively niche use-case.


We might end up going that way, but it would be a shame IMO. Though 
splitting it out might be useful. Python documentation is packaged into 
chapters which are self contained and reasonably readable. We should 
strive for the same.


As we move increasingly towards different kinds of content 
(blogs/notebooks/tutorials), I think we should try to keep all users in 
mind and PDF generation is hardly on its way out in any language / 
library.


--- Rohit

On 22 May 2022, at 23:28, Stephan Hoyer wrote:


On Sun, May 22, 2022 at 3:52 PM 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.


The HTML docs can also be downloaded for offline use.

Perhaps someone has access to analytics from numpy.org that can tell 
us how
often the PDF docs are viewed? I believe PDFs could be more convenient 
for
some use-cases, but I don't think it's worth the trouble of the 
separate

rendering pipeline for a relatively niche use-case.



___
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: rgosw...@quansight.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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Charles R Harris]

On Sun, May 22, 2022 at 4:54 PM 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.
>

If they were just hard to read, I'd be happy to distribute them. The
problem is that they are hard to generate. Latex is limited, and we depend
on Sphinx to generate it. When it breaks, as it does, it is also hard to
debug because the error messages are cryptic, and at best refer to the
generated latex code, which doesn't help track down the problem. I think it
would be worth exploring html -> pdf converters, they might be better
supported.



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: arch...@mail-archive.com

[Numpy-discussion] Re: Dropping the pdf documentation.

[Matti Picus]

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

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.



Matti

___
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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Ralf Gommers]

On Mon, May 23, 2022 at 1:31 AM Stephan Hoyer  wrote:

> On Sun, May 22, 2022 at 3:52 PM 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.
>>
> The HTML docs can also be downloaded for offline use.
>
> Perhaps someone has access to analytics from numpy.org that can tell us
> how often the PDF docs are viewed? I believe PDFs could be more convenient
> for some use-cases, but I don't think it's worth the trouble of the
> separate rendering pipeline for a relatively niche use-case.
>

Unfortunately https://numpy.org/doc/ is a separate site from
https://numpy.org/. The latter is built with Hugo and we have analytics for
it, the former is built with Sphinx and we don't have analytics for it.

Cheers,
Ralf
___
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

[Numpy-discussion] Re: Dropping the pdf documentation.

[Ralf Gommers]

On Mon, May 23, 2022 at 6:51 AM Matti Picus  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
> >  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-le...@python.org
https://mail.python.org/mailman3/lists/numpy-discussion.python.org/
Member address: arch...@mail-archive.com