I am unaware of the state of the SciPy documentation at the time it was
dropped. However, many of these arguments do not seem to apply to the
NumPy documentation hosted at https://numpy.org/doc/.
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
This is a valid concern, but there are third-party tools to deal with
reflow (both at the mobile level and by preprocessing like with
k2pdfopt: https://www.willus.com/k2pdfopt/)
Almost all links are broken and left as double backticks since it is
not originally designed for PDF navigation
There are no broken links in our User Guide, and even external links
(e.g. `PyObject` links to the Python documentation) work. Internal links
to different parts of the PDF also work.
I have not read our Reference Guide cover to cover in a while (other
than the NumPy-C API chapter) but I do not remember any backticks
anywhere. Please correct me if this is incorrect.
Code copy/pasting is broken (due to how the TeX package for listings
setup) regardless of the PDF viewer
This isn't the case for Firefox's PDF viewer and others I have tried
(Adobe, Zathura). Though on Linux most pdf copy-pastes can be a little
difficult.
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.
Untrue, our typography and layout might not be perfect but we do not
have a lot of empty space.
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)
We have a reasonable 30 minute timeout for the `pdf` build and we have
discussed running this less frequently.
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)
Also can be mitigated, we can shift to `tectonic` or simply use a custom
`texlive` install to have less packages (for the size issue).
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.
We don't have markdown sources?
I understand that perhaps SciPy's documentation was in far worse shape
than NumPy, but we shouldn't paint with a broad brush.
-- Rohit
On 23 May 2022, at 8:41, Ilhan Polat wrote:
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.gomm...@gmail.com>
wrote:
On Mon, May 23, 2022 at 6:51 AM Matti Picus <matti.pi...@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.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
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: ilhanpo...@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
