summaryrefslogtreecommitdiff
path: root/Documentation/sphinx
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2016-03-06 20:29:31 -0700
committerJani Nikula <jani.nikula@intel.com>2016-05-30 13:38:53 +0300
commit89a66d76109935aad387a5058f120aeb8246ae40 (patch)
tree256f6bd0d8f5b56ad2fbf87da4625e2a625335e8 /Documentation/sphinx
parentc13ce448c8532965eb4e1115e78cb5b8ff8261a3 (diff)
sphinx: cheesy script to convert .tmpl files
This script uses pandoc to convert existing DocBook template files to RST templates. A couple of sed scripts are need to massage things both before and after the conversion, but the result is then usable with no hand editing. [Jani: Change usage to tmplcvt <in> <out>. Fix escaping for docproc directives. Add support the new kernel-doc extension.] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Diffstat (limited to 'Documentation/sphinx')
-rw-r--r--Documentation/sphinx/convert_template.sed14
-rw-r--r--Documentation/sphinx/post_convert.sed19
-rwxr-xr-xDocumentation/sphinx/tmplcvt19
3 files changed, 52 insertions, 0 deletions
diff --git a/Documentation/sphinx/convert_template.sed b/Documentation/sphinx/convert_template.sed
new file mode 100644
index 000000000000..d53bb8220a26
--- /dev/null
+++ b/Documentation/sphinx/convert_template.sed
@@ -0,0 +1,14 @@
+#
+# Pandoc doesn't grok <function> or <structname>, so convert them
+# ahead of time.
+#
+# Use "$bq" instead of "`" so that pandoc won't mess with it.
+#
+s%<function>\([^<(]\+\)()</function>%:c:func:$bq\1$bq%g
+s%<function>\([^<(]\+\)</function>%:c:func:$bq\1$bq%g
+s%<structname>struct *\([^<]\+\)</structname>%:ref:$bqstruct \1$bq%g
+s%<structname>\([^<]\+\)</structname>%:ref:$bqstruct \1$bq%g
+#
+# Wrap docproc directives in para and code blocks.
+#
+s%^\(!.*\)$%<para><code>DOCPROC: \1</code></para>%
diff --git a/Documentation/sphinx/post_convert.sed b/Documentation/sphinx/post_convert.sed
new file mode 100644
index 000000000000..ce17049f6a8e
--- /dev/null
+++ b/Documentation/sphinx/post_convert.sed
@@ -0,0 +1,19 @@
+#
+# pandoc thinks that both "_" needs to be escaped. Remove the extra
+# backslashes. Also put in proper backquotes now that pandoc won't quote
+# them.
+#
+s/$bq/`/g
+s/\\_/_/g
+#
+# Unwrap docproc directives.
+#
+s/^``DOCPROC: !E\(.*\)``$/.. kernel-doc:: \1\n :export:/
+s/^``DOCPROC: !I\(.*\)``$/.. kernel-doc:: \1\n :internal:/
+s/^``DOCPROC: !F\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :functions: \2/
+s/^``DOCPROC: !P\([^ ]*\) \(.*\)``$/.. kernel-doc:: \1\n :doc: \2/
+s/^``DOCPROC: \(!.*\)``$/.. WARNING: DOCPROC directive not supported: \1/
+#
+# Trim trailing whitespace.
+#
+s/[[:space:]]*$//
diff --git a/Documentation/sphinx/tmplcvt b/Documentation/sphinx/tmplcvt
new file mode 100755
index 000000000000..909a73065e0a
--- /dev/null
+++ b/Documentation/sphinx/tmplcvt
@@ -0,0 +1,19 @@
+#!/bin/bash
+#
+# Convert a template file into something like RST
+#
+# fix <function>
+# feed to pandoc
+# fix \_
+# title line?
+#
+
+in=$1
+rst=$2
+tmp=$rst.tmp
+
+cp $in $tmp
+sed --in-place -f convert_template.sed $tmp
+pandoc -s -S -f docbook -t rst -o $rst $tmp
+sed --in-place -f post_convert.sed $rst
+rm $tmp