Furthermore, the PDF docs of numpy (and maybe scipy) can be stripped to a
separate project and put on a separate release cycle, not necessarily
tracking the releases.
On Mon, May 23, 2022 at 10:37 AM Ralf Gommers <ralf.gomm...@gmail.com>
wrote:
>
>
> On Mon, May 23, 2022 at 10:21 AM Lev Maximov <lev.maxi...@gmail.com>
> wrote:
>
>> What do you guys think of the chm format ("windows help")? This offline
>> documentation format is shipped with all python releases (eg
>> https://www.python.org/downloads/release/python-3913/).
>> 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.
>
>
>
>>
>> Best regards,
>> Lev
>>
>> On Mon, May 23, 2022 at 1:33 PM 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.
>>>
>>
> 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
>
> _______________________________________________
> 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: rainwood...@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
