[jira] [Created] (COUCHDB-3068) Docs fail to build with Sphinx 1.4+

["Joan Touzet (JIRA)" <ji...@apache.org>]

Joan Touzet created COUCHDB-3068:
------------------------------------

             Summary: Docs fail to build with Sphinx 1.4+
                 Key: COUCHDB-3068
                 URL: https://issues.apache.org/jira/browse/COUCHDB-3068
             Project: CouchDB
          Issue Type: Bug
          Components: Documentation
            Reporter: Joan Touzet


After updating my local install of Sphinx to 1.4, I get the following error in the build:

{noformat}
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  0%] about
writing output... [  1%] api/basics

Warning, treated as error:
/home/joant/couchdb/src/docs/src/api/basics.rst:144: WARNING: Could not lex literal_block as "http". Highlighting skipped.
{noformat}

Because we specify {{-W}} on the {{sphinx-build}} line, we treat all warnings as errors the build stops here. Removing the -W allows the build to complete but results in 255 warnings where highlighting is being skipped as a result of a failure to parse the block. The full output of {{make html}} is here: https://paste.apache.org/DKOL

The temporary fix is to disable the -W option in the makefile. [~janl] [~andywenk] this is something you might want to think about for the RC2 release, though I suspect your local Sphinx is old enough that it's not running into the bug.

The right fix is to fix the code blocks so they work under Sphinx 1.4+. See for instance [this diff|http://dpdk.org/dev/patchwork/patch/14861/] of how another project fixed their warnings - it's mainly un-escaping some text since the parser expects no syntax errors in the block of text.

If no one else steps up by mid- next week I can look at this bug, but my time is booked until July 27th at the earliest.



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)