PDF documentation links in Documentation from Jupyter notebook are broken

[strogdon]

To replicate the issue:

• ./configure --enable-sagemath_doc_pdf=yes
• make
• ./sage -n jupyter
• select New -> [SageMath](../wiki/SageMath) xxxx
• select Help -> Sage Documentation

Clicking on any of the PDF icons gives, for example, in the terminal:

[W 20:13:44.654 NotebookApp] Kernelspec name pdf cannot be found!
[W 20:13:44.655 NotebookApp] 404 GET /kernelspecs/pdf/en/tutorial/SageTutorial.pdf (::1): Kernel spec pdf not found
[W 20:13:44.656 NotebookApp] 404 GET /kernelspecs/pdf/en/tutorial/SageTutorial.pdf (::1) 2.920000ms referer=http://localhost:8888/kernelspecs/sagemath/doc/index.html

with a corresponding 404 : Not Found browser page

Note:

if Sage is configured with --enable-sagemath_doc_pdf=no then PDF documentation icons/links will not appear in the Documentation.

CC: @jhpalmieri @kwankyu

Component: documentation

Author: Steven Trogdon, Kwankyu Lee

Branch/Commit: 4b6ac0f

Reviewer: Kwankyu Lee, Steven Trogdon

Issue created by migration from https://trac.sagemath.org/ticket/33206

[strogdon]

comment:1

The issue seems to arise from the web server not being able to deal with ../.. in code like

        <a title="Download PDF" class="pdf" href="../../pdf/en/tutorial/SageTutorial.pdf">
          <img class="icon" src="_static/pdf.png"></img>
        </a>

from src/doc/en/website/templates/index.html. A work-a-round is to replace ../.. with a symlink web_pdf -> ../.. and then to add the symlink to Sage.

[strogdon]

Branch: u/strogdon/pdf_docs_broken_jupyter_notebook

[strogdon]

comment:3

The referenced symlink is created under sagemath_doc_html/spkg-install since src/doc/en/website/templates/index.html needs to be changed. I have not included a method to remove the created symlink, web_pdf as necessary. I'm not sure where that should be done, if needed.

---

New commits:

0a30a52

fix broken links to PDF documentation in the Sage documentation

[strogdon]

Commit: 0a30a52

[strogdon]

Author: Steven Trogdon

[kwankyu]

New commits:

c6c309e

A bit cleaner symlink

[kwankyu]

Changed commit from 0a30a52 to c6c309e

[kwankyu]

Changed branch from u/strogdon/pdf_docs_broken_jupyter_notebook to public/33206

[kwankyu]

comment:8

It seems (1) we only need the symlink in the "website" directory, and (2) the symlink creation is the job of the sphinx "website" builder.

I also removed a deprecated method on the way.

[kwankyu]

Changed author from Steven Trogdon to Steven Trogdon, Kwankyu Lee

[strogdon]

comment:10

Replying to @kwankyu:

It seems (1) we only need the symlink in the "website" directory, and (2) the symlink creation is the job of the sphinx "website" builder.

I also removed a deprecated method on the way.

Unless I'm mistaken, in addition to now creating the pdf symlink under the "website" folder the entire pdf tree under local/share/doc/sage/pdf had been copied to local/share/doc/sage/html/en/pdf. Is this intended?

[strogdon]

comment:11

OK, so the copied stuff under local/share/doc/html/en/pdf are needed for the PDF links to work in the Documentation. Couldn't this be a symlink? I'm not sure what the created symlink under the "website" folder does. If I move local/share/doc/html/en/pdf out of the way the links in the Documentation are broken.

[sagetrac-git]

Changed commit from c6c309e to bb2ac9c

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

bb2ac9c

Fix a bug

[kwankyu]

comment:13

Replying to @strogdon:

Unless I'm mistaken, in addition to now creating the pdf symlink under the "website" folder the entire pdf tree under local/share/doc/sage/pdf had been copied to local/share/doc/sage/html/en/pdf. Is this intended?

Never. It was my mistake to put the symlink pdf to the website folder, which triggered the whole copy. Now it is put in the folder one level up.

[kiwifb]

comment:15

The absolute link is a bit of an issue in my opinion. It certainly can lead to problem in distros where SAGE_DOC at build time is different from SAGE_DOC at runtime once everything is put in place. Vanilla sage builds in place of course so doesn't see that problem.

So my suggestion is something like https://stackoverflow.com/questions/54825010/why-does-os-symlink-uses-path-relative-to-destination

html_output_dir = self._output_dir('html')
pdf_doc_dir = os.path.join(SAGE_DOC, 'pdf')
relpath = os.path.relpath(pdf_doc_dir, os.path.join(html_output_dir, '..', 'pdf'))

try:
      os.symlink(relpath, os.path.join(html_output_dir, '..', 'pdf'))
except FileExistsError:
      pass

[sagetrac-git]

Changed commit from bb2ac9c to 4b6ac0f

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

4b6ac0f

Use relative path for symlink

[kwankyu]

comment:17

Replying to @kiwifb:

The absolute link is a bit of an issue in my opinion. It certainly can lead to problem in distros where SAGE_DOC at build time is different from SAGE_DOC at runtime once everything is put in place. Vanilla sage builds in place of course so doesn't see that problem.

Okay.

[strogdon]

comment:18

This does work.

@kwankyu remove me as an author if approprite since you knew where to make the real changes.

[strogdon]

Reviewer: Steven Trogdon

[kwankyu]

comment:19

Replying to @strogdon:

This does work.

@kwankyu remove me as an author if approprite since you knew where to make the real changes.

No. You knew that, and I followed you. Thanks.

[kwankyu]

Changed reviewer from Steven Trogdon to Kwankyu Lee, Steven Trogdon

[slel]

comment:21

Hope this can get in Sage 9.5.

[vbraun]

Changed branch from public/33206 to 4b6ac0f