From 7d9a8a5797c6264449d2d185546a3a7de759b4a0 Mon Sep 17 00:00:00 2001
From: Radovan Bast <bast@users.noreply.github.com>
Date: Thu, 4 Jun 2015 15:59:55 +0200
Subject: [PATCH] extract documentation from cmake modules

---
 doc/conf.py           |  3 ++
 doc/extract_rst.py    | 75 +++++++++++++++++++++++++++++++++++++++++++
 doc/index.rst         |  1 +
 modules/version.cmake | 12 ++++---
 4 files changed, 86 insertions(+), 5 deletions(-)
 create mode 100644 doc/extract_rst.py

diff --git a/doc/conf.py b/doc/conf.py
index 7704ab3..fcdcf21 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -16,6 +16,9 @@ import sys
 import os
 import shlex
 
+sys.path.append(os.path.relpath(os.path.abspath('.')))
+import extract_rst
+
 # 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.
diff --git a/doc/extract_rst.py b/doc/extract_rst.py
new file mode 100644
index 0000000..d2e1169
--- /dev/null
+++ b/doc/extract_rst.py
@@ -0,0 +1,75 @@
+import glob
+import os
+import ntpath
+
+#-------------------------------------------------------------------------------
+
+def extract_rst_blobs(s_in):
+    s_out = []
+    is_rst_line = False
+    for line in s_in.split('\n'):
+        if is_rst_line:
+            if len(line) > 0:
+                if line[0] != '#':
+                    is_rst_line = False
+            else:
+                is_rst_line = False
+        if is_rst_line:
+            s_out.append(line[2:])
+        if '#.rst:' in line:
+            is_rst_line = True
+    return '\n'.join(s_out)
+
+def test_extract_rst_blobs():
+    s_in = '''# a
+# b
+#.rst:
+# c
+#  d
+
+# e
+# f
+g
+h
+# i
+# j
+#.rst:
+# k
+# l'''
+    s_out = '''c
+ d
+k
+l'''
+
+    assert s_out == extract_rst_blobs(s_in)
+
+#-------------------------------------------------------------------------------
+
+def main():
+
+    THIS_DIR = os.path.dirname(os.path.realpath(__file__))
+
+    output = []
+    output.append("Module reference")
+    output.append("================")
+    output.append("\n")
+
+    files = glob.glob('%s/*.cmake' % os.path.join(THIS_DIR, '..', 'modules'))
+
+    for f in files:
+        file_name = ntpath.basename(f)
+        output.append('\n\n%s' % file_name)
+        output.append('-'*len(file_name))
+        with open(f, 'r') as s:
+            s_out = extract_rst_blobs(s.read())
+            if s_out == '':
+                output.append('\nNo documentation\n')
+            else:
+                output.append(s_out)
+
+    with open(os.path.join(THIS_DIR, 'module-reference.rst'), 'w') as f:
+        f.write('\n'.join(output))
+
+#-------------------------------------------------------------------------------
+
+main()
diff --git a/doc/index.rst b/doc/index.rst
index cae4664..a9ffd8e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -10,3 +10,4 @@ Autocmake
    new-project.rst
    customizing-modules.rst
    updating-modules.rst
+   module-reference.rst
diff --git a/modules/version.cmake b/modules/version.cmake
index 06d118e..b4015cf 100644
--- a/modules/version.cmake
+++ b/modules/version.cmake
@@ -1,8 +1,10 @@
-# determine program version from file, example: "14.1"
-# the reason why this information is stored
-# in a file and not as cmake variable
-# is that cmake-unaware programs can
-# parse and use it (e.g. Sphinx)
+#.rst:
+#
+# Determine program version from file "VERSION" (example: "14.1")
+# The reason why this information is stored
+# in a file and not as CMake variable is that CMake-unaware programs can parse
+# and use it (e.g. Sphinx).
+
 if(EXISTS "${PROJECT_SOURCE_DIR}/VERSION")
     file(READ "${PROJECT_SOURCE_DIR}/VERSION" PROGRAM_VERSION)
     string(STRIP "${PROGRAM_VERSION}" PROGRAM_VERSION)