[flang-commits] [PATCH] D86131: [FLANG] Pick `.md` files when building sphinx documentation.

[sameeran joshi via Phabricator via flang-commits]

sameeranjoshi created this revision.
sameeranjoshi added reviewers: sscalpone, richard.barton.arm, DavidTruby, Bigcheese.
Herald added subscribers: aaron.ballman, dexonsmith.
Herald added a project: LLVM.
sameeranjoshi requested review of this revision.

Need to build sphinx using below flags to Cmake
`-DLLVM_ENABLE_SPHINX=ON -DSPHINX_WARNINGS_AS_ERRORS=OFF`.
Generate html docs using cmake target
`docs-flang-html`
Generated html files should be at `build/tools/flang/docs/html`.
Patch in series from the dicussion on review
https://reviews.llvm.org/D85828

After this patch the markdown docmentation must be written using guide in-
llvm/docs/MarkdownQuickstartTemplate.md


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D86131

Files:
  flang/docs/conf.py


Index: flang/docs/conf.py
===================================================================
--- flang/docs/conf.py
+++ flang/docs/conf.py
@@ -21,7 +21,6 @@
 
 # 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']
@@ -29,14 +28,32 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+extensions = ['recommonmark']
+
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {
+    '.rst': 'restructuredtext',
+}
+try:
+  import recommonmark
+except ImportError:
+  # manpages do not use any .md sources
+  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_suffix['.md'] = 'markdown'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'ReleaseNotes'
+master_doc = 'Overview'
 
 # General information about the project.
 project = u'Flang'
@@ -196,7 +213,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('ReleaseNotes', 'Flang.tex', u'Flang Documentation',
+  ('Overview', 'Flang.tex', u'Flang Documentation',
    u'The Flang Team', 'manual'),
 ]
 
@@ -237,7 +254,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('ReleaseNotes', 'Flang', u'Flang Documentation',
+  ('Overview', 'Flang', u'Flang Documentation',
    u'The Flang Team', 'Flang', 'One line description of project.',
    'Miscellaneous'),
 ]


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D86131.286238.patch
Type: text/x-patch
Size: 2037 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/flang-commits/attachments/20200818/2b564aa6/attachment.bin>