New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[SR-620] Building Documentation with Sphinx 1.3.5 fails: Could not parse literal_block as "swift" #43237
Comments
cc @jckarter, @dabrahams |
Since the documentation is build by the build script automatically this prevents even basic actions using the build script like creating the Xcode project using utils/build-script -x -- --reconfigure |
For anyone coming across this issue: To resolve it for now, install Sphinx version 1.3.4, e.g. using easy_install Sphinx==1.3.4 |
Comment by Hitster GTD (JIRA) @ahoppen, |
I finally took a look at this and I'm rather confused, because the literal block does look like valid pygments-Swift. (That is, when I pass it directly to the SwiftLexer defined in utils/pygments/, I get colorized output.)
I'll remove the warning-as-error for now. |
Actually, it looks like every highlight is broken. I think someone else really has to look at this properly. I was using this to test what was actually being passed to
|
Thanks for investigating and removing the warnings-as-errors flag. I guess we can remove the note saying that newer versions of sphinx are not supported from README.md in the main repository now, can’t we? |
I didn't actually end up removing it (because of the spew of output). Since the contents of the literal block seem to actually be correct, I'm not sure what's going on. |
Pinging @dabrahams again, since IIRC he was the one to set it up in the first place. |
OK, thanks! |
I’m afraid that if I set up syntax highlighting for our docs, I don’t remember anything about it. |
I don't think anyone else has ever worked with Sphinx or Pygment lexers, though. I don't want to just switch to the default Swift lexer (if they have one) because ours is a lot more lax, which makes sense when proposing new things. Maybe we can just disable this one warning, even if it means syntax highlighting is inconsistent? Or we can drop the syntax highlighting altogether. |
Weren’t there plans to switch to markdown for the documentation anyway? I don’t know where and when I heard it, so I may be wrong. |
Comment by Farhan Ahmed (JIRA) This is also happening with Sphinx 1.4.4. I get the following when building the docs: Warning, treated as error: Any possible work around to at least let build finish? |
Comment by Link Dupont (JIRA) FWIW, I could reproduce this by calling |
Comment by Jason Zavaglia (JIRA) I've taken a look at this - I think the Pygments is throwing an error - the grammar specified in the lexer is not fully correct - and the build error is due to Sphinx being more strict post 1.3.4 The very first code block to be attempted to be formatted is this one, which I spent a bit of time in the debugger looking at.
This immediately raises exceptions when trying to parse "var x: Int" The definition of
to...
This isn't actually sufficient to get it to work completely, as the lexer is still not terminating correctly at the very end of successfully processing the buffer - not exactly sure why. Even if I one were to fix this, it would only fix the very first case, and there are likely to be more problems in the grammar which are uncovered with other code snippets in the documentation - so there is probably a fair bit of work and testing to be done here - it would be worth putting some test cases in there I think. I hope that helps gives some clarity on the problem, I may try to come back to it later. |
Comment by Jeremy Fergason (JIRA) I took a look at the lexer and got most of the warnings resolved. This implements a couple of extra lexers for the SIL and ABI code blocks. (see attached patch) lexer.diff There are still some lingering issues though, mostly with SIL.rst:
These seem to revolve around sphinx getting confused about parsing the file. |
Thanks for the patch, Jeremy! (And thanks for the initial triage, Link and Jason.) I finally got back to this and think I've resolved all the issues. See #4283 |
If this resolves all the issues (I haven't tested yet), we should change easy_install -U Sphinx==1.3.4 in easy_install -U Sphinx |
Committed to master in ca14c36. |
Waiting for someone else to verify the fix before I update the README. |
I have tested everything with Sphinx 1.4.5. Thanks for fixing this! |
Great! README updated in d318c95. |
Attachment: Download
Environment
Sphinx 1.3.5
Additional Detail from JIRA
md5: f29451f0a4f28cf621fa382441a0a9d3
is duplicated by:
Issue Description:
Building the Swift documentation with the latest Sphinx (1.3.5 released Jan 24, 2016) fails with the following error message:
Because the warning is treated as an error, it is currently not possible to build the documentation using the makefile with Sphinx 1.3.5
This is probably related because issue #1565 was fixed in Sphinx (http://www.sphinx-doc.org/en/stable/changes.html)
For a discussion on this problem see: sphinx-doc/sphinx#2264
The text was updated successfully, but these errors were encountered: