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)
