Fix some remaining issues with sphinx-1.0.4.p3.spkg

[jdemeyer]

This ticket is a follow-up to #10118 (merged in sage-4.6.1.alpha2)

Here are some trivial problems in the file SPKG.txt of version ".p3" of the Sphinx package:

• In the section

  == Dependencies ==
  
  This depends on Jinja >= 2, Pygments >= 0.8, and docutils >= 0.4.
  

  we should have "Pygments >= 1.3.1" due to ticket #10290, and "Jinja2 >= 2.2". But this is no biggy; it's a trivial typo that can either (i) be fixed in a new ticket, or (ii) fixed in the current ticket.

• In the section

  * patches/pngmath.patch: This replaces \usepackage[utf8x]{inputenc}
    by \usepackage[utf8]{inputenc} in the LaTeX preamble for building
    images in the HTML documentation.  This change is done because some
    LaTeX installations have only utf8, not utf8x (utf8x adds support for
    much more Unicode characters, but these are needed used to typeset the
    mathematics in the Sage documentation).
  

  the fragment

  but these are needed used to typeset the
  

  should be changed to

  but these are used to typeset the
  

Tested on the following platforms:

• {sage.math, bsd.math, hawk}: Both HTML and PDF versions of documentation built OK. For the PDF version, building the reference manual produced some warnings about "unusable reference target", which are to do with relative links to other documents in the Sage standard documentation.

• {cleo, iras}.skynet: Sage 4.6.1.alpha2 fails to build on this machine, hence the documentation doesn't get built at all.

• {cicero, eno, lena, sextus, taurus, t2}: The HTML version of the documentation mostly built OK, but with warnings about a missing LaTeX installation. Consequently, the PDF version of the documentation can't be built.

• flavius.skynet -- The PDF version of the documentation built fine, but with some warnings about unusable relative links. The HTML version built with numerous warnings due to missing the dvipng command.

• {gcc11, gcc16}.fsffrance.org: The HTML version of all documents in the standard documentation mostly built OK, but with warnings about the missing command "dvipng". This machine has a LaTeX installation, but it is missing the file titlesec.sty, hence building the PDF version of any document in the standard documentation would hang at the error message:

  Style option: `fancybox' v1.3 <2000/09/19> (tvz)
  )
  
  ! LaTeX Error: File `titlesec.sty' not found.
  
  Type X to quit or <RETURN> to proceed,
  or enter new name. (Default extension: sty)
  

• rh.math: The HTML version of all documents in the standard documentation mostly built OK, but with warnings about the missing command "dvipng". This means that LaTeX typesetting does not render at all in the HTML version. This machine has a LaTeX installation, but it is missing the file utf8x.def, hence building any document in the standard documentation would hang at the error message that prompts for utf8x.def. Note that we have the patch

  src/sphinx/ext/pngmath.py

  @@ -34 +34 @@
   
   DOC_HEAD = r'''
   \documentclass[12pt]{article}
  -\usepackage[utf8x]{inputenc}
  +\usepackage[utf8]{inputenc}
   \usepackage{amsmath}
   \usepackage{amsthm}
   \usepackage{amssymb}

  to use only utf8 instead of utf8x. The same change needs to be made to the file doc/common/conf.py. See my reviewer patch trac-10118_use-utf8.patch. With this patch, we get pass the issue of the missing utf8x.def, but we now run into the following error:

  Style option: `fancybox' v1.3 <2000/09/19> (tvz)
  )
  
  ! LaTeX Error: File `titlesec.sty' not found.
  
  Type X to quit or <RETURN> to proceed,
  or enter new name. (Default extension: sty)
  

Apply:

•  http://sage.math.washington.edu/home/jdemeyer/spkg/sphinx-1.0.4.p5.spkg

[jdemeyer]

New spkg:  http://sage.math.washington.edu/home/jdemeyer/spkg/sphinx-1.0.4.p4.spkg

[jdemeyer]

Patch from p3 to p4, for review

[leif]

From sage-release:

I have an interesting (repeatable) error.

Processing dependencies for Sphinx==1.0.4
Searching for Jinja2>=2.2
Reading http://pypi.python.org/simple/Jinja2/
Download error: [Errno 8] nodename nor servname provided, or not known
-- Some packages may not be found!
Reading http://pypi.python.org/simple/Jinja2/
Download error: [Errno 8] nodename nor servname provided, or not known
-- Some packages may not be found!
Couldn't retrieve index page for 'Jinja2'
Scanning index of all packages (this may take a while)
Reading http://pypi.python.org/simple/
Download error: [Errno 8] nodename nor servname provided, or not known
-- Some packages may not be found!
No local packages or download links found for Jinja2>=2.2
error: Could not find suitable distribution for
Requirement.parse('Jinja2>=2.2')
Error building Sphinx: 'Error installing Sphinx'
real	0m3.594s
user	0m1.063s
sys	0m0.514s
sage: An error occurred while installing sphinx-1.0.4.p3


This sort of mystified me, and retyping 'make' didn't help, until I
plugged my computer back into the Internet.  Then I got:


Processing dependencies for Sphinx==1.0.4
Searching for Jinja2>=2.2
Reading http://pypi.python.org/simple/Jinja2/
Reading http://jinja.pocoo.org/
Best match: Jinja2 2.5.5
Downloading http://pypi.python.org/packages/source/J/Jinja2/Jinja2-2.5.5.tar.gz#md5=83b20c1eeb31f49d8e6392efae91b7d5


and all is well.

Is the internet now a prerequisite for building Sage?  Obviously it is
a prereq for downloading it, but in theory one would want to be able
to build it while offline (or to buy a CD with the source, or
whatever).  I am pretty sure that in the past this was not supposed to
be true.

- kcrisman

[leif]

P.S.: We should catch such automatically by grep -iw downloading install.log.

[leif]

We have the correct dependencies in spkg/standard/deps:

$(INST)/$(SPHINX): $(BASE) $(INST)/$(JINJA2) $(INST)/$(PATCH)
        $(INSTALL) "$(SAGE_SPKG) $(SPHINX) 2>&1" "tee -a $(SAGE_LOGS)/$(SPHINX).log"

but our Jinja2 is too old:

~/Sage/sage-4.6.1.alpha2$ ls spkg/standard/jinja2-* 
spkg/standard/jinja2-2.1.1.p0.spkg

[leif]

CC'ing the Jinja2 spkg maintainers.

[leif]

I think an upgraded Jinja2 spkg is on the way, just a little patience...

[leif]

I've opened #10423 for a new Jinja2 spkg (2.5.5), coming up soon.

[leif]

Replying to leif:

I've opened #10423 for a new Jinja2 spkg (2.5.5), coming up soon.

Upgraded Jinja2 spkg ready for review.

[jdemeyer]

Replying to leif:

P.S.: We should catch such automatically by grep -iw downloading install.log.

Done, thanks for the suggestion.

[mvngu]

Tested on the following machines together with sphinx-1.0.4.p4.spkg and jinja2-2.5.5.p0.spkg. I put these updated packages in the source tarball of Sage 4.6.1.alpha2 and built Sage from source. After a successful build from source, I grep'd through install.log for the word "Downloading" as follows:

$ grep -iw 'Downloading' install.log

Grep'ing through the various install.log files didn't show any signs of packages being downloaded during the build.

• {cleo, iras}.skynet: Sage didn't build from source, so the documentation can't be built at all.

• {cicero, eno, lena, sextus, taurus, t2}: The HTML version of the documentation built OK, but with warnings about a missing LaTeX installation so LaTeX expressions won't be nicely typeset in the generated HTML files. There wasn't a LaTeX installation on this machine, so I wasn't able to build the PDF version of the documentation.

• flavius.skynet: The HTML version of the documentation built OK, but with warnings about the missing 'dvipng' command, so the LaTeX expressions won't be nicely typeset in the generated HTML files. The PDF version built OK.

• {gcc11, gcc16}.fsffrance.org: The HTML version of the documentation built OK. The PDF didn't build at all due to the following error:

  ! LaTeX Error: File `titlesec.sty' not found.
  

  The documentation build process didn't hang at the above error, but continued on until the end.

• rh.math: The HTML version of the documentation built OK, but with warnings about missing the command 'dvipng' so LaTeX expressions won't be nicely typeset in the generated HTML files. The PDF version of the documentation didn't build at all. The relevant error is:

  ! LaTeX Error: File `utf8x.def' not found.
  

  The documentation build process didn't hang at the above error, but continued on until the end.

• {bsd, hawk, sage}: Both the HTML and PDF versions of the documentation built OK.

I'm OK with all changes in the updated spkg. But note the following minor issues:

1. In the following line of SPKG.txt

   This depends on Jinja >= 2, Pygments >= 1.3.1, docutils >= 0.4.
   

   the part "Jinja >= 2," should be changed to "Jinja >= 2.5.5," as per ticket #10423.
2. The change log for sphinx-1.0.4.p4 should reference the number of the current ticket.

If the above changes are made, this ticket should get a positive review.

[leif]

Replying to mvngu:

1. In the following line of SPKG.txt

This depends on Jinja >= 2, Pygments >= 1.3.1, docutils >= 0.4.

the part "Jinja >= 2," should be changed to "Jinja >= 2.5.5," as per ticket #10423.

I'd say >=2.2 as required by this Sphinx version; 2.5.5 is currently the latest.

Btw, any ideas about Jinja2's true dependencies (cf. this comment)?

Upstream only explicitly mentions Python and setuptools (alternatively, preferably "distribute").

[jdemeyer]

New spkg:  http://sage.math.washington.edu/home/jdemeyer/spkg/sphinx-1.0.4.p5.spkg

[jdemeyer]

p4 to p5 patch for reference

[mvngu]

The updated spkg is good to go. Thanks!

[leif]

Stylewise, I would have used a make variable for redirecting stdin.

This could easily be modified without touching the patch at all.

I would also use utf8 instead of utf8x conditionally, i.e., first check if utf8x is available.

[jdemeyer]

Replying to leif:

Stylewise, I would have used a make variable for redirecting stdin.

I suppose there is no harm in doing this, but I don't see much gain either.

I would also use utf8 instead of utf8x conditionally, i.e., first check if utf8x is available.

Why? I dislike conditional stuff without a good reason.

[leif]

Replying to jdemeyer:

Replying to leif:

Stylewise, I would have used a make variable for redirecting stdin.

I suppose there is no harm in doing this, but I don't see much gain either.

It's more flexible and eases maintaining, in any case.

I would also use utf8 instead of utf8x conditionally, i.e., first check if utf8x is available.

Why? I dislike conditional stuff without a good reason.

I don't like generally disabling things or introducing artificial limits just because there are problems on some platforms or installations.

In the case of utf8x, it's not unlikely someone would use it for his documents, or Sage documentation in other languages perhaps, and it should be more wide-spread in the future (while I assume disabling it in Sage will last for a long time...)

[jdemeyer]

Replying to leif:

In the case of utf8x, it's not unlikely someone would use it for his documents, or Sage documentation in other languages perhaps.

If that happens, we need to completely drop support for utf8. A conditional build is also pointless in this case.