8000 Add PDF download of documentation · Issue #20859 · scikit-learn/scikit-learn · GitHub
[go: up one dir, main page]
Skip to content

Add PDF download of documentation #20859

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
cwfoo opened this issue Aug 27, 2021 · 14 comments
Open

Add PDF download of documentation #20859

cwfoo opened this issue Aug 27, 2021 · 14 comments
Labels
Documentation

Comments

@cwfoo
Copy link
cwfoo commented Aug 27, 2021 •
edited
Loading

Describe the issue linked to the documentation

In the list of documentation downloads (https://scikit-learn.org/dev/versions.html), the documentation for the latest scikit-learn version (0.24.2) is not available as a PDF download. The documentation for prior versions of scikit-learn are available in PDF format. See #17051, #17564 and #19208.

2021-08-27_17-57

Suggest a potential alternative/fix

Please add a PDF of the documentation for scikit-learn 0.24.2.
@cwfoo cwfoo changed the title Add PDF download for documentation Add PDF download of documentation Aug 27, 2021
@KiranHipparagi
Copy link

can i contribute to this issue?

@KiranHipparagi
Copy link

@cwfoo could you please help me to find the file where exactly it's located?I'm new to open source project..

@cwfoo
Copy link
Author
cwfoo commented Aug 27, 2021 •
edited
Loading

@KiranHipparagi This is the relevant piece of code:

scikit-learn/build_tools/circle/list_versions.py

Lines 36 to 44 in 15a9494

def get_file_extension(version):
if 'dev' in version:
# The 'dev' branch should be explictly handled
return 'zip'
current_version = LooseVersion(version)
min_zip_version = LooseVersion('0.24')
return 'zip' if current_version >= min_zip_version else 'pdf'

Apparently, they stopped generating PDF documentation because of #17051.

@thomasjpfan
Copy link
Member

Thank you for opening the issue @cwfoo !

That is correct, we no longer generate the PDF.

@cwfoo
Copy link
Author
cwfoo commented Aug 28, 2021

@thomasjpfan Why was this issue closed? Does the closing of this issue indicate that the request to reinstate PDF documentation downloads would not be considered?

@thomasjpfan
Copy link
Member

Yes, we do not plan to generate PDFs at this time. The reasons why we made the decision is in #17051

@thomasjpfan
Copy link
Member
thomasjpfan commented Aug 28, 2021 •
edited
Loading

Thinking about it again, I'll reopen this issue for discussion. The main concern with generating PDFs was that it was a big maintenance burden as stated in #17051 (comment)

@cwfoo What is your use case for the PDF version of the documentation?

@thomasjpfan thomasjpfan reopened this Aug 28, 2021
@cwfoo
Copy link
Author
cwfoo commented Aug 30, 2021

@thomasjpfan

What is your use case for the PDF version of the documentation?

  • For printing.
  • For reading on an e-book reader.

When printed or when displayed on e-book readers, the issue is that HTML documents could have strange formatting (if the printing/reading program attempts to remove sidebars/headers) or the sidebars/headers waste lots of space (if the printing/reading program does not remove sidebars/headers). In any case, HTML files are generally not the best format from which to print documents, or for reading on an e-book reader.

@glemaitre
Copy link
Member

I am -1 to go back on the PDF generation due to the maintenance burden. I would also advocate against printing the documentation to save a couple of trees in the process.

Then, I don't know if we can generate an ePUB from sphinx that would not break every other day.

@NicolasHug
Copy link
Member

@cwfoo have you tried html -> pdf converters such as pandoc?

@cwfoo
Copy link
Author
cwfoo commented Sep 6, 2021

@thomasjpfan @glemaitre Another issue with the zipped HTML documentation is that the math is not rendered when offline. I've opened a separate issue for that — #20951.

@atulsaurav
Copy link

There is a huge value to this for having it on e-readers. If I can understand that it was a huge overhead for PRs as things kept breaking. Another options may be to publish the steps needed to self generate the pdf with a disclaimer that its fragile and not supported.. and people try it at their own risk.. This will open up possibilities of people using using partial pdfs or finding other ways to work around it...

@glemaitre
Copy link
Member

It is indeed documented there: https://scikit-learn.org/dev/developers/contributing.html?highlight=build%20documentation#building-the-documentation

make latexpdf

@cmatKhan
Copy link

There is a huge value to this for having it on e-readers. If I can understand that it was a huge overhead for PRs as things kept breaking. Another options may be to publish the steps needed to self generate the pdf with a disclaimer that its fragile and not supported.. and people try it at their own risk.. This will open up possibilities of people using using partial pdfs or finding other ways to work around it...

I agree with this -- there is huge value in having it on an e-reader

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
7 participants
@NicolasHug @thomasjpfan @atulsaurav @glemaitre @cwfoo @cmatKhan @KiranHipparagi
0