8000 Fix broken PDF generation for the documentation · Issue #3830 · scikit-learn/scikit-learn · GitHub
[go: up one dir, main page]
Skip to content

Fix broken PDF generation for the documentation #3830

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
Closed
falconair opened this issue Nov 6, 2014 · 10 comments · Fixed by #3900
Closed

Fix broken PDF generation for the documentation #3830

falconair opened this issue Nov 6, 2014 · 10 comments · Fixed by #3900
Labels
Bug Moderate Anything that requires some knowledge of conventions and best practices

Comments

@falconair
Copy link

The documentation for this project looks fantastic. I'm new to ML but I'd love to have a PDF copy of the docs which I can read along with text books on the subject.

I just spend half a day trying to do 'make latexpdf' only to find out that pdf functionality hasn't worked in over a year.

Can you please just provide a pdf copy of the manual and save lots of people lots of time and frustration. Even the sourceforge email lists are full of people asking for the pdf.
@GaelVaroquaux
Copy link
Member

Can you please just provide a pdf copy of the manual and save lots of people
lots of time and frustration.

Pull request welcomed.

@nareshshah139
Copy link

The pdf can be downloaded from http://sourceforge.net/projects/scikit-learn/files/documentation/

@falconair
Copy link
Author

Unfortunately the latest PDF there is for version 0.12 (from 2012), while current version seems to be 0.15.2

@ogrisel
Copy link
Member
ogrisel commented Nov 21, 2014

When I run make pdflatex I get an error that I don't get when running make html:

________________________________________________________________________________
[Memory] Calling gen_rst._get_data...
_get_data('/Users/ogrisel/code/scikit-learn/doc/_build/latex/searchindex.js')

Exception occurred:
  File "/Users/ogrisel/code/scikit-learn/doc/sphinxext/gen_rst.py", line 111, in _get_data
    with open(url, 'r') as fid:
FileNotFoundError: [Errno 2] No such file or directory: '/Users/ogrisel/code/scikit-learn/doc/_build/latex/searchindex.js'
The full traceback has been saved in /var/folders/69/7jxl92h50w10b4v998qt4tj00000gn/T/sphinx-err-dstz9mzs.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make: *** [latexpdf] Error 1

It's probably a bug in our gen_rst machinery. That should be skipped when not building for the HTML format.

@ogrisel ogrisel added Bug Moderate Anything that requires some knowledge of conventions and best practices labels Nov 21, 2014
@ogrisel ogrisel changed the title Can we please get a PDF of the user guide Fix broken PDF generation for the documentation Nov 21, 2014
@ogrisel
Copy link
Member
ogrisel commented Nov 21, 2014

It's likely that this is only the first of a series of issues to get the PDF doc to generate correctly. If someone wants to have a deeper look that would be great. This requires a working latex install on your system.

8000

@dimazest
Copy link
Contributor

Here is the pdf after disabling the gen_rst sphinx plugin. https://dl.dropboxusercontent.com/u/50040986/user_guide.pdf

I guess, the plugin shouldn't register itself when pdf is generated.

@jnothman
Copy link
Member

Without gen_rst, many images, and link targets (those corresponding to
examples), will not exist. It is better if the examples are included in the
PDF.

On 29 November 2014 at 23:24, Dmitrijs Milajevs notifications@github.com
wrote:

Here is the pdf after disabling the gen_rst sphinx plugin.
https://dl.dropboxusercontent.com/u/50040986/user_guide.pdf

I guess, the plugin shouldn't register itself when pdf is generated.

—
Reply to this email directly or view it on GitHub
#3830 (comment)
.

@dimazest
Copy link
Contributor

@jnothman could you please check the generated pdf.

actually, the problem is in embed_code_links:

diff --git a/doc/sphinxext/gen_rst.py b/doc/sphinxext/gen_rst.py
index ed216f0..15fab76 100644
--- a/doc/sphinxext/gen_rst.py
+++ b/doc/sphinxext/gen_rst.py
@@ -971,6 +971,10 @@ def embed_code_links(app, exception):
         return
     print('Embedding documentation hyperlinks in examples..')

+    if app.builder.name == 'latex':
+        # Don't embed hyperlinks when a latex builder is used.
+        return
+
     # Add resolvers for the packages for which we want to show links
     doc_resolvers = {}
     doc_resolvers['sklearn'] = SphinxDocLinkResolver(app.builder.outdir,

dimazest added a commit to dimazest/scikit-learn that referenced this issue Nov 29, 2014
@dimazest
Don’t embed hyperlinks during latex file generation.
e52b763 
Should fix scikit-learn#3830
@dimazest dimazest mentioned this issue Nov 29, 2014
Merged
@jnothman
Copy link
Member

That's good; it has allowed the PDF to build, yet has not produced a sensible form of documentation. In the PDF version:

  • there should be a table-of-contents
  • there seem to be many chapters that should really be sections of other chapters (e.g. the one on fetching covertype; changelong entries)
  • what would be thumbnails corresponding to examples on the web site show up as duplicated images in the examples themselves, as well as as in the examples associated with each class/function in the reference
  • assume within-documentation references should be hyperlinked, but do not seem to be in cases where I've looked

@ogrisel
Copy link
Member
ogrisel commented Nov 29, 2014

@jnothman I agree, I will create a new issue for this.

@ogrisel ogrisel mentioned this issue Nov 29, 2014
Closed
jlopezpena pushed a commit to jlopezpena/scikit-learn that referenced this issue Nov 30, 2014
@dimazest
Don’t embed hyperlinks during latex file generation.
50dec1f 
Should fix scikit-learn#3830
jmetzen pushed a commit to jmetzen/scikit-learn that referenced this issue Dec 13, 2014
@dimazest
Don’t embed hyperlinks during latex file generation.
f6dd82d 
Should fix scikit-learn#3830
@nelson-liu nelson-liu mentioned this issue Dec 5, 2015
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Bug Moderate Anything that requires some knowledge of conventions and best practices
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[MRG+1] Don’t embed hyperlinks during latex file generation. dimazest/scikit-learn
6 participants
@jnothman @ogrisel @GaelVaroquaux @falconair @dimazest @nareshshah139
0