On Mon, May 23, 2022 at 11:12 AM Rohit Goswami <rgosw...@quansight.com> wrote:
> 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/. > They were almost identical, same machinery (like most things). Well this is subjective but the typography is unfit for any code based format. > 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/) > The contents are nonresponsive. No tool can fix a native responsiveness issues. I am familiar with those tools. The questions is why work so hard when you have the HTML already? > 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. > OK this one was on me. I've updated the reader and now things went back to normal. Sorry for the noise. > 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. > All mentioned viewers fail to retain the format of the code and copy as text. You should paste it to somewhere to get the problem. Unless it is single line in the examples the rest is not really working properly. In case you are not familiar there are quite a number of ways to fix this but definitely not worth the effort. > Untrue, our typography and layout might not be perfect but we do not have > a lot of empty space. > This is demonstrably true, the document margins are against quite a few technical document typography rules (mostly how page setup and typeface choices are done). It is as it is because the documentation is also following an indentation format very much like Python code which uses whitespace too generously. The document itself is quite an eyesore if you care about those things.np.einsum is a prime example how it shouldn't render in a PDF document. All choices are coming from the indentation of markdown. Because it uses none of the advantages of a PDF. That is typography and font layout. It cannot use it because the source is not providing context. Because it is coming from a function signature. This is also related to Markdown comment below. > We have a reasonable 30 minute timeout for the pdf build and we have > discussed running this less frequently. > This doesn't change the fact that you are downloading way too many complex tools and moving images that are bloated. Just because it is free does not justify its use. It is just a huge waste to repeat that excessive compilation each and every time. I would also say it is a bit on the irresponsible side. > Also can be mitigated, we can shift to tectonic or simply use a custom > texlive install to have less packages (for the size issue). > No. This is still a very large payload mainly due to the typography tools are used and their dependencies. Maintaining a custom TeXLive is just asking for trouble since the packages are updated very frequently (I know because we tried this many times at work to keep a mobile Receipt generator). > 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? > What I mean is that LaTeX source is text-based with context in it. But we are providing markdown sources. This causes problems in the meantime both in translation and also layout. > I understand that perhaps SciPy's documentation was in far worse shape > than NumPy, but we shouldn't paint with a broad brush > That's not true. They are almost identical. These are common issues that still exists in the NumPy version. To be honest, it is very hard to make a case for PDF in its given condition. You can still compile and use it. We shouldn't continue bothering with it at the CI level just because there is a marginal interest in it. I am not ranting about NumPy because SciPy. This is a very bad TeX design and to fix it we have to get away from auto-doc generation which I am sure none of us want for now. That is unfortunately how good docs are now today, mathworks constantly being praised about it despite its notoriety. Hence I don't see any case for keeping generating this PDF. If you want to have a proper doc effort, that is a whole another story and I would love to have that but this doc generated PDF is not worth of any nonnegligable value. And if you think it is then you can generate it yourself. The tools are not going to be removed anyways.
_______________________________________________ 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
