Upgrade Sphinx version used in docs builds (Trac #550)

[smk78]

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?

Migrated from http://trac.sasview.org/ticket/550

{
    "status": "closed",
    "changetime": "2016-04-12T15:02:19",
    "_ts": "2016-04-12 15:02:19.727798+00:00",
    "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!)\n\nOne 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.\n\nMy 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.\n\nSo 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'.\n\nI tried a sasmodels doc build again, but it still complained about the numrefs.\n\nSo then I did a 'pip install --upgrade sphinx' which has dragged in Sphinx-1.3.6.\n\nI'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...\n\nFrom 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.\n\nI 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.\n\nQ1. What version of Sphinx is on the build servers?\n\nQ2. Should be update the build servers to 1.3.6?\n ",
    "reporter": "smk78",
    "cc": "",
    "resolution": "fixed",
    "workpackage": "SasView Documentation",
    "time": "2016-03-22T19:19:45",
    "component": "SasView",
    "summary": "Upgrade Sphinx version used in docs builds",
    "priority": "blocker",
    "keywords": "",
    "milestone": "SasView 4.0.0",
    "owner": "",
    "type": "defect"
}

[smk78]

Trac update at 2016/04/12 15:02:03: smk78 commented:

From !GoTo 12 Apr 16:

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

So am closing this ticket.

[smk78]

Trac update at 2016/04/12 15:02:19:

• smk78 changed resolution from "" to "fixed"
• smk78 changed status from "new" to "closed"