Opened 3 years ago

Closed 3 years ago

#550 closed defect (fixed)

Upgrade Sphinx version used in docs builds

Reported by: smk78 Owned by:
Priority: blocker Milestone: SasView 4.0.0
Component: SasView Keywords:
Cc: Work Package: SasView Documentation

Description

During Code Camp IV some of those present had issues with :numref: tags not rendering properly in the built html docs (though I didn't!)

One returning to my office I pulled on sasmodels and sasview to bring my desktop up to date, and then went to build the sasmodels docs. I got 5 warnings, 3 of them the same :numref: errors that people had seen at Code Camp. I think I now understand why.

My desktop and laptop both have Anaconda dev envs installed as per Peter's instructions on the wiki. For some reason my desktop had Sphinx-1.2.3 and Sphinx-1.3.1 installed but (as far as check_packages was concerned) was using 1.2.3 for doc builds. My laptop only had 1.3.1 installed.

So I did a 'pip uninstall sphinx' on my desktop, followed by a 'pip install sphinx'. The latter resulted in the message 'Requirement already satisfied…Sphinx-1.3.1'.

I tried a sasmodels doc build again, but it still complained about the numrefs.

So then I did a 'pip install —upgrade sphinx' which has dragged in Sphinx-1.3.6.

I've run the doc build again and, hey-ho, the numref warnings have gone! It may be my imagination but I also think this newer version of Sphinx built with fewer PyOpenCL compiler output messages…

From googling around I have determined that numref is definitely NOT supported by Sphinx versions prior to 1.3.1 unless you install you install Sphinx patch 4773.

I haven't been able to conclusively PROVE that there is an issue with 1.3.1 also - after all my laptop seemed to build the docs ok - but we clearly need to be careful about what version of Sphinx we do use.

Q1. What version of Sphinx is on the build servers?

Q2. Should be update the build servers to 1.3.6?

Change History (2)

comment:1 Changed 3 years ago by smk78

From GoTo 12 Apr 16:

ESS Build Machines have: OSX 10.10 = 1.4, W7 = 1.3.6

So am closing this ticket.

comment:2 Changed 3 years ago by smk78

  • Resolution set to fixed
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.