-
Notifications
You must be signed in to change notification settings - Fork 2.1k
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
Use reStructuredText's code
directive
#2155
Comments
I think neither option is great. In the first case, Sphinx would have a half-compatible I think option 3 might be better: to acknowledge that Sphinx RST is a slightly different language than Docutils RST (library-wise, not syntax-wise), and to only support |
Docutils uses |
Unfortunately, Sphinx doesn't support code highlighting for standard reStructuredText `code` directive. So let's register 'code' directive as alias for Sphinx's own implementation. See sphinx-doc/sphinx#2155 for details.
I was wondering why my attempts to get syntax highlighting of inline code were not working, and it looks like this is maybe the problem. I have this role defined:
and in my document I use <code class="code python docutils literal notranslate">
<span class="keyword"><span class="pre">print</span></span>
<span class="punctuation"><span class="pre">(</span></span>
<span class="literal string double"><span class="pre">“hi”</span></span>
<span class="punctuation"><span class="pre">)</span></span>
</code> I have a .highlight .k { color: #007020; font-weight: bold } /* Keyword */ All I need to do is add the relevant selectors to the appropriate definitions: .highlight .k, .code .keyword { color: #007020; font-weight: bold } /* Keyword */ It seems like it would be relatively easy to distribute such a custom CSS file until a proper solution is found, but maybe there are other complexities I'm not considering? |
This issue was filed about the |
I just posted a PR #6132 for latter idea. Personally, I prefer former one. Because I'd not like to distinguish two style of "code block" directives. I suspect they will confuse users. So it would be better to start discussion about integration of them. My opinion is adding docutils originated options to |
Closes #2155: Support ``code`` directive
The code directive is implemented and seems to mirror docutils, though it's not documented on sphinx-doc.org since we recommend using |
Since docutils 0.9, reStructuredText supports
code
directive, but Sphinx, unfortunately, can't handle this. By design,code
directive supports syntax highlighting, but Sphinx ignores this due tovisit_literal_block
reimplementation in customHTMLTranslator
.So basically:
code
directive as literal block.Well, I see two possible ways to solve this issue:
Use Sphinx's
CodeBlock
implementation forcode
directive:Pros:
code-block
/sourcecode
Cons:
Use docutils' (native) implementation for
code
directive.Pros:
Cons:
visit_literal_block
implementation for non-Sphinx code blocksshort
Pygments CSS notation to docutils (long
is default)code-block
optionsFolks, could you please share your opinion on this?
@birkenfeld It'd be nice to see your input.
The text was updated successfully, but these errors were encountered: