[Sphinx] Adjust for source_parsers deprecation in Sphinx 3.0

[JDevlieghere]

Summary

Update the Sphinx configuration for the removal of source_parsers in Sphinx 3.0. The variable has been deprecated since version 1.8.

Version 1.8 deprecates and version 3.0 removes the source_parsers configuration variable that was used by older recommonmark versions.

https://www.sphinx-doc.org/en/master/usage/markdown.html

[JDevlieghere]

Don't bump the minimum sphinx version as the bot's are running 1.7. Before this land we should verify that the new config variable works with older Sphinx.

[hans]

I don't really know anything about Sphinx, but sounds good to me if it works I guess :-)

[sylvestre.ledru]

thanks!

[sylvestre.ledru]

it breaks the build on Debian stable (and probably some Ubuntu LTS). With sphinx 1.8.4
Could you please revert the change ?

Sphinx error:
Source parser for markdown not registered

[mehdi_amini]

Ping here?

It seems like even the most recent version of the package is still 0.4 and this change seems to require 0.5: https://packages.ubuntu.com/groovy/python3-recommonmark

llvm.org/docs aren't regenerated for a few days, I don't know if it is related?

[JDevlieghere]

Make the change conditional on the Sphinx version.

[JDevlieghere]

Would someone with this setup be able to test this?

[mehdi_amini]

This patch works on my machine right now!

Is the sphinx version a direct indicator of the recommonmark version?

[JDevlieghere]

In D75284#2118207, @mehdi_amini wrote:

This patch works on my machine right now!

Is the sphinx version a direct indicator of the recommonmark version?

Thanks for checking, Mehdi! No, it is not, but given that Sphinx deprecates the old behavior, there's no way to make recommonmark < 0.5 with Sphinx > 3.0, at least to the best of my understanding.

llvm/docs/conf.py

 
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo', 'recommonmark']
+extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.todo']
+
+import sphinx
+if sphinx.version_info >= (3, 0):
+  # This requires 0.5 or later.
+  extensions.append('recommonmark')
+else:
+  source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = {
     '.rst': 'restructuredtext',
     '.md': 'markdown',