extract documentation from cmake modules

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.

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()

doc/index.rst

@@ -10,3 +10,4 @@ Autocmake
    new-project.rst
    customizing-modules.rst
    updating-modules.rst
+   module-reference.rst

modules/version.cmake

@@ -1,8 +1,10 @@
-# determine program version from file, example: "14.1"
+#.rst:
-# the reason why this information is stored
+#
-# in a file and not as cmake variable
+# Determine program version from file "VERSION" (example: "14.1")
-# is that cmake-unaware programs can
+# The reason why this information is stored
-# parse and use it (e.g. Sphinx)
+# 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)