[Flang][Docs] Fix warnings when building docs.

[sameeranjoshi]

Summary

Following warning were seen with recommonmark(0.5.0) and sphinx(1.8.5).
parser.py:75: UserWarning: Container node skipped: type=document warn("Container node skipped: type={0}".format(mdnode.t))

The warnings are due to an issue in recommonmark's(a python package) older versions.
A better solution is to use the latest version of recommonmark(>=0.6.0) to avoid
these issue in the first place.
This patch fixes the warnings for older versions.

[jdoerfert]

flang/docs/index.md

50

Was this intended?

[sameeranjoshi]

flang/docs/index.md

50

It was other warning which comes from toctree.
I fixed it with this patch.

[jdoerfert]

LGTM

flang/docs/conf.py

 # -*- coding: utf-8 -*-
 # Flang documentation build configuration file.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
 import sys, os
 from datetime import date
+from recommonmark.parser import CommonMarkParser
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
+# https://github.com/readthedocs/recommonmark/issues/177
+#Method used to remove the warning message.
+class CustomCommonMarkParser(CommonMarkParser):
+    def visit_document(self, node):
+        pass
+
+
 # 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.todo', 'sphinx.ext.mathjax', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
except ImportError:
   if not tags.has('builder-man'):
     raise
 else:
   import sphinx
   if sphinx.version_info >= (3, 0):
     # This requires 0.5 or later.
     extensions.append('recommonmark')
   else:
-    source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+    source_parsers = {'.md': CustomCommonMarkParser}
   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.

flang/docs/index.md

.. toctree::
    f2018-grammar.md
    OpenMP-4.5-grammar.md
    Directives
    Extensions
    Intrinsics
    OptionComparison
    ParserCombinators
    RuntimeDescriptor
+   RuntimeTypeInfo
    Calls
    Character
    ArrayComposition
    BijectiveInternalNameUniquing
 ```
 
 # Indices and tables
 
 ```eval_rst
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
 ```