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

[Igor Kudrin via Phabricator via llvm-commits]

ikudrin created this revision.
ikudrin added reviewers: rupprecht, jhenderson, ddunbar, Bigcheese.
Herald added a subscriber: dexonsmith.
Herald added a project: LLVM.

rL358749 <https://reviews.llvm.org/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.


Repository:
  rL LLVM

https://reviews.llvm.org/D60964

Files:
  docs/conf.py


Index: docs/conf.py
===================================================================
--- docs/conf.py
+++ docs/conf.py
@@ -11,7 +11,7 @@
 # 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,
@@ -223,12 +223,25 @@
 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.search("^\# (\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')
@@ -243,12 +256,20 @@
                 ("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 not name in ('index.rst',):
+        process_rst(name)
+
 # If true, show URL addresses after external links.
 #man_show_urls = False
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D60964.196059.patch
Type: text/x-patch
Size: 2362 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190422/c199694e/attachment.bin>