[DOCS] Sphinx 4.x.y compatibility fixes #11420
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
cameel
commented
May 20, 2021
Comment on lines
+5
to
+6
| # Sphinx 2.1.0 is the oldest version that accepts a lexer class in add_lexer() | ||
| sphinx>=2.1.0 |
There was a problem hiding this comment.
Added this because b_docs job is failing. Apparently there is an ancient version of Sphinx (v1.8.5) already installed in the image.
cameel
force-pushed
the
docs-sphinx-4-compatibility-fixes
branch
from
5eff7b5
to
1ee64f4
Compare
|
This needs more work. Looks like |
|
Lexer problem reported in |
|
Looks good, but I think the test extractor needs to be updated. |
…r shell and text snippets
…pygments-lexer-solidity
cameel
force-pushed
the
docs-sphinx-4-compatibility-fixes
branch
from
1ee64f4
to
98c4830
Compare
cameel
changed the base branch from
develop
to
fix-isolate-tests-parsing-sphinx-block-parameters
|
Extractor fixed in #11565. This PR is now based on it. I'll mark it as reviewable once the dependency is merged. |
Base automatically changed from
fix-isolate-tests-parsing-sphinx-block-parameters
to
develop
June 22, 2021 09:01
chriseth
approved these changes
Jun 22, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Depends on #11565.
Sphinx 4.0.0 has been released recently and deprecated some of the older features. Now
scripts/docs.shfails for me locally on that version. This PR adds some minor tweaks to make our docs work with both Sphinx 3 and Sphinx 4:add_stylesheet()has long been deprecated.add_css_file()is the replacement (AttributeError: 'Sphinx' object has no attribute 'add_stylesheet' sphinx-doc/sphinx#7747). This has exposed a bug in our lexer. See details below.add_lexer()used to accept both a class and an instance. Starting with Sphinx 4 it only accepts a lexer class.robots.txtto.gitignore. This is unrelated to Sphinx update and should have been done in script to automate updates to robots.txt (v2) #11317.Bug in
pygments-lexer-solidityadd_lexer()has a weird quirk:WARNING: Could not lex literal_block as "Solidity". Highlighting skipped.) and highlighting is completely disabled for the buggy code snippet.This has exposed a bug in pygments-lexer-solidity. The lexer apparently has problems handling
assemblyblocks that are followed by other Solidity instructions (but extra instructions before them are fine). Note for example the red outline in one of the examples in our current docs:The error goes away only if I remove the
returnstatement or theassemblyblock. We have 3 snippets like this. The snippets look fine to me and do compile so it must be a bug in the lexer rather than in the snippet.I originally wanted to use theEDIT: Weird, it only works locally. I did need:force:option of thecode-blockdirective to suppress these errors until the lexer is fixed. But it turns out that switching from::tocode-blockwas enough to suppress them.:force:to make it build in CI.