Allow one to set a default language for code blocks

[anntzer]

It would be practical if one could set a default language for highlighting code blocks -- e.g. through a buffer-local variable. A use case is of course python documentation where :: will most often introduce a python code block. For example, https://github.com/davidhalter/jedi-vim/blob/master/autoload/jedi.vim#L351 could benefit from this. A more complex use case may be perhaps to have a ftplugin look for a .. highlight:: (set default highlighting language) and set the config appropriately, but that's more hypothetical.

[marshallward]

I would love this, but is it possible to do this at the reST level? If not, then I wonder if it could be misleading.

[anntzer]

Sphinx has .. highlight:: which sets the default language (http://www.sphinx-doc.org/en/stable/markup/code.html). Now a quick look suggests (I'm not sure) that this is not part of the docutils spec; on the other hand apparently the docutils spec for code highlighting is .. code:: (http://docutils.sourceforge.net/docs/ref/rst/directives.html#code) and not .. code-block::, whereas sphinx's docs only mention the later. (Basically I'm arguing that the sphinx spec is the relevant one here, not the docutils spec.)

[marshallward]

Supporting this is no problem, I wasn't familiar with the highlight directive. And a normal reST file would not have this tag, so it's easily ignored.

As you can tell from the other tickets I don't have much time to devote to the stylesheet these days. The biggest hurdle is just a general lack of familiarity with vimscript. Getting this working might take more a community effort.

(And as always, I'm happy to hand over maintenance to someone with more vimscript experience.)

[anntzer]

There's no hurry, I'm fine with this issue tracker being a TODO list :-) I can probably implement this "at some point" but #reallife is also catching up.

[marshallward]

That's a relief to hear! I love reST and vim, so I'm happy there's someone else out there who feels the same, and would hate to get in the way of that :).

[anntzer]

Note for whoever tries to implement this (perhaps myself): it may be possible (or not) to implement this in a reasonably robust manner by having .. highlight:: start a new region defined by recursively eval'ing the current syntax file, but with a special variable (setting the default highlighting language) set; then, when defining rstLiteralBlock, check whether that variable is set.

[blueyed]

I was about to file a new issue, but this seems fitting! :)

Sphinx allows for using highlighting with literal code blocks by default (via highlight_language), and defaults to "python" there (falling back to "none", https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-highlight_language).

It would be great if this would be supported by the syntax.

It seems like this might warrant a setting, and maybe/also a general setting to enable Sphinx's extensions in general? Here a buffer-local variable was mentioned already - and it could try to parse previous highlight directives (but that might be slow). In general it might be good to have a global, that can also be set as a buffer variable, and would maybe even default to "python" (maybe if "sphinx mode" is enabled only then).

It might also be enough documenting how you can extend it yourself - since it only adds to the "contains" after all.

diff --git i/runtime/syntax/rst.vim w/runtime/syntax/rst.vim
index c865cf690..fa6356542 100644
--- i/runtime/syntax/rst.vim
+++ w/runtime/syntax/rst.vim
@@ -20,9 +20,15 @@ syn cluster rstCruft                contains=rstEmphasis,rstStrongEmphasi>
       \ rstInterpretedText,rstInlineLiteral,rstSubstitutionReference,
       \ rstInlineInternalTargets,rstFootnoteReference,rstHyperlinkReference
 
+" NOTE: Sphinx uses Python by default, via "highlight_language" setting.
+" Therefore add @rstpython, for:
+"
+" Some code::
+"
+"     print("python!")
 syn region  rstLiteralBlock         matchgroup=rstDelimiter
       \ start='::\_s*\n\ze\z(\s\+\)' skip='^$' end='^\z1\@!'
-      \ contains=@NoSpell
+      \ contains=@NoSpell,@rstpython
 
 syn region  rstQuotedLiteralBlock   matchgroup=rstDelimiter
       \ start="::\_s*\n\ze\z([!\"#$%&'()*+,-./:;<=>?@[\]^_`{|}~]\)"

[marshallward]

Seems like a great idea, and I agree that some sort of "Sphinx-mode" might be useful in other situations too.

I'm a bit out of time at the moment, but if you send in something then I can merge it.

[blueyed]

Cool. I do not have much time myself, and the above works good for me already. Let me know what you have in mind: g:rst_syntax_sphinx_mode ? In theory this could be auto-enabled based on looking for a conf.py file, but I would argue that it is likely good to enable it by default maybe then - at least for this feature, which could be enabled by g:rst_syntax_literal_highlight (python in this case).

I have not yet investigated/check how easy it would be to do the above patch via vimrc, but is likely not hard, and more flexible then altogether - this would mean it could be added to docs for now then only.

[marshallward]

Maybe the simplest path for now is to just introduce a default syntax for code blocks, since it's the only Sphinx-specific we're talking about at the moment.

Sphinx uses highlight_language, so I am thinking something ilke rst_highlight_language or rst_sphinx_highlight_language. But any choice is fine with me.

I could see a suite of Sphinx-friendly flags being added over time, since there are several directives and things which are slightly different in reST and Sphinx. One that comes to mind is the .. code:: vs .. code-block:: thing - which we already handle somewhat - but I think there are many more, some of which @anntzer has alluded to in the past. But I reckon we can wait until there are a few more Sphinx-specific (and reST-incompatible) components before worrying too much about it.