Uploaded image for project: 'CouchDB'
  1. CouchDB
  2. COUCHDB-3068

Docs fail to build with Sphinx 1.4+

    XMLWordPrintableJSON

    Details

    • Type: Bug
    • Status: Closed
    • Priority: Critical
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.0.0
    • Component/s: Documentation
    • Labels:
    • Skill Level:
      New Contributors Level (Easy)

      Description

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

      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.
      

      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. Jan Lukavsk√Ĺ Andy Wenk 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 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.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                kxepal Alexander Shorin
                Reporter:
                wohali Joan Touzet
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: