[docs] Add support for Markdown documentation when creating man pages

[ikudrin]

Summary

rL358749 added a documentation page for a new tool in the Markdown format. Currently, the configuration script ignores such pages when building the man pages.

[jhenderson]

docs/conf.py

235–238 ↗

(On Diff #196059)

There seems to be an excessive number of brackets to me here. Can this be simplified slightly to something like (with one or two line breaks in other places as required):

print(
  "error: invalid title in %r (expected '# <name> - <description>')" % file_subpath,
  file=sys.stderr)

[ikudrin]

• Simplified print statements.
• Added escaping in the regex string.

[jhenderson]

LGTM, I think (not verified the regex though). Have you discussed using markdown for documentation with anybody else though?

[MaskRay]

docs/conf.py

233 ↗

(On Diff #197528)

m = re.match(r'^# (\S+) - (.+)$', title)

250 ↗

(On Diff #197528)

Use single quotes for consistency.

[MaskRay]

docs/conf.py

267 ↗

(On Diff #197528)

not name in ('index.rst',) -> name != 'index.rst'

[ikudrin]

In D60964#1485943, @jhenderson wrote:

LGTM, I think (not verified the regex though).

Thanks!

Have you discussed using markdown for documentation with anybody else though?

No. The documentation for llvm-addr2line is the only page for a command line tool in the Markdown format. That was requested by @rupprecht in D60067#1466153.

[ikudrin]

• Updated according to @MaskRay's comments.

llvm/docs/conf.py

 # -*- coding: utf-8 -*-
 #
 # LLVM 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.
 from __future__ import print_function
 
-import sys, os
+import sys, os, re
 from datetime import date
 
 # 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 -----------------------------------------------------

 man_pages = []
 
 # Automatically derive the list of man pages from the contents of the command
 # guide subdirectory.
 basedir = os.path.dirname(__file__)
 man_page_authors = "Maintained by the LLVM Team (https://llvm.org/)."
 command_guide_subpath = 'CommandGuide'
 command_guide_path = os.path.join(basedir, command_guide_subpath)
-for name in os.listdir(command_guide_path):
-    # Ignore non-ReST files and the index page.
-    if not name.endswith('.rst') or name in ('index.rst',):
-        continue
 
-    # Otherwise, automatically extract the description.
+
+def process_md(name):
+    file_subpath = os.path.join(command_guide_subpath, name)
+    with open(os.path.join(command_guide_path, name)) as f:
+        title = f.readline().rstrip('\n')
+
+        m = re.match(r'^# (\S+) - (.+)$', title)
+        if m is None:
+            print("error: invalid title in %r "
+                  "(expected '# <name> - <description>')" % file_subpath,
+                  file=sys.stderr)
+        else:
+            man_pages.append((file_subpath.replace('.md',''), m.group(1),
+                              m.group(2), man_page_authors, 1))
+
+
+def process_rst(name):
     file_subpath = os.path.join(command_guide_subpath, name)
     with open(os.path.join(command_guide_path, name)) as f:
         title = f.readline().rstrip('\n')
         header = f.readline().rstrip('\n')
 
         if len(header) != len(title):
-            print((
-                "error: invalid header in %r (does not match title)" % (
-                    file_subpath,)), file=sys.stderr)
+            print('error: invalid header in %r (does not match title)' %
+                  file_subpath, file=sys.stderr)
         if ' - ' not in title:
-            print((
-                ("error: invalid title in %r "
-                 "(expected '<name> - <description>')") % (
-                    file_subpath,)), file=sys.stderr)
-
+            print("error: invalid title in %r "
+                  "(expected '<name> - <description>')" % file_subpath,
+                  file=sys.stderr)
         # Split the name out of the title.
         name,description = title.split(' - ', 1)
         man_pages.append((file_subpath.replace('.rst',''), name,
                           description, man_page_authors, 1))
 
+
+for name in os.listdir(command_guide_path):
+    # Process Markdown files
+    if name.endswith('.md'):
+        process_md(name)
+    # Process ReST files apart from the index page.
+    elif name.endswith('.rst') and name != 'index.rst':
+        process_rst(name)
+
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
 # FIXME: Define intersphinx configuration.
 intersphinx_mapping = {}
 
 # Pygment lexer are sometimes out of date (when parsing LLVM for example) or
 # wrong. Suppress the warning so the build doesn't abort.
 suppress_warnings = [ 'misc.highlighting_failure' ]
 
 # Direct html-ified man pages to llvm.org
 manpages_url = 'https://llvm.org/docs/CommandGuide/{page}.html'