[flang] Fix docs build

[richard.barton.arm]

Summary

Apply a local fix to an issue with recommonmark's AutoStructify extension
when used with certain versions of sphinx.

See https://github.com/readthedocs/recommonmark/issues/93

[hans]

Nice! I tried this out, and it appears to work.

[richard.barton.arm]

Gone for the merge.

@sameeranjoshi - happy to make adjustments if you have any feedback.

To fix this on the branch we need to cherry-pick af56be3 .

[hans]

Cherry-picked to the branch as 8f2c29681ce768afb739b6cf5ccca81dd87d5326.

flang/docs/conf.py

if sphinx.version_info >= (3, 0):
     extensions.append('recommonmark')
   else:
     source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
   source_suffix['.md'] = 'markdown'
   extensions.append('sphinx_markdown_tables')
 
   # Setup AutoStructify for inline .rst toctrees in index.md
   from recommonmark.transform import AutoStructify
+
+  # Stolen from https://github.com/readthedocs/recommonmark/issues/93
+  # Monkey patch to fix recommonmark 0.4 doc reference issues.
+  from recommonmark.states import DummyStateMachine
+  orig_run_role = DummyStateMachine.run_role
+  def run_role(self, name, options=None, content=None):
+    if name == 'doc':
+      name = 'any'
+      return orig_run_role(self, name, options, content)
+  DummyStateMachine.run_role = run_role
+
   def setup(app):
     # Disable inline math to avoid
     # https://github.com/readthedocs/recommonmark/issues/120 in Extensions.md
     app.add_config_value('recommonmark_config', {
       'enable_inline_math': False
     }, True)
     app.add_transform(AutoStructify)