feat(doc): def for DO NOT EDIT comments

A note like that is now added to all files we generated, commented out
depending on the file type.

Quite neat, except that for filtering, I always have to use blocks.

src/mako/LICENSE.md.mako

@@ -1,5 +1,9 @@
 ## -*- coding: utf-8 -*-
 <%! import util %>\
+<%namespace name="mutil" file="lib/util.mako"/>\
+<%block filter="util.markdown_comment">\
+<%mutil:gen_info source="${self.uri}" />\
+</%block>
 The MIT License (MIT)
 =====================
 

src/mako/README.md.mako

@@ -1,5 +1,9 @@
+<%! import util as pyutil %>\
 <%namespace name="lib" file="lib/lib.mako"/>\
 <%namespace name="util" file="lib/util.mako"/>\
+<%block filter="pyutil.markdown_comment">\
+<%util:gen_info source="${self.uri}" />\
+</%block>
 The `${util.library_name()}` library allows access to all features of *${canonicalName}*.
 
 <%lib:docs />

src/mako/cargo.toml.mako

@@ -1,8 +1,8 @@
 <%! import util %>\
 <%namespace name="mutil" file="lib/util.mako"/>\
-# DO NOT EDIT !
-# This file was generated automatically by '${self.uri}'
-# DO NOT EDIT !
+<%block filter="util.hash_comment">\
+<%mutil:gen_info source="${self.uri}" />\
+</%block>
 [package]
 
 name = "${mutil.library_name()}"

src/mako/deps.mako

@@ -18,8 +18,10 @@
 	api_json_inputs = api_json + " $(API_SHARED_INFO)"
 	api_info.append((api_name, api_clean, gen_root))
 %>\
-${api_common}: $(RUST_SRC)/cmn.rs
-	@cp $< $@
+${api_common}: $(RUST_SRC)/cmn.rs $(lastword $(MAKEFILE_LIST))
+	@ echo "// COPY OF '$<'"  > $@
+	@ echo "// DO NOT EDIT"  >> $@
+	@cat $< >> $@
 
 ${gen_root_stamp}: ${' '.join(i[0] for i in sds)} ${api_json_inputs} $(MAKO_LIB_FILES) $(MAKO_RENDER)
 	PYTHONPATH=$(MAKO_LIB_DIR) $(TPL) --template-dir '.' --var OUTPUT_DIR=$@ -io ${' '.join("%s=%s" % (s, d) for s, d in sds)} --data-files ${api_json_inputs}

src/mako/lib.rs.mako

@@ -8,6 +8,10 @@
 <%namespace name="lib" file="lib/lib.mako"/>\
 <%namespace name="mutil" file="lib/util.mako"/>\
 <%namespace name="schema" file="lib/schema.mako"/>\
+<%block filter="util.rust_comment">\
+<%mutil:gen_info source="${self.uri}" />\
+</%block>
+
 <%block filter="util.rust_module_doc_comment">\
 <%lib:docs />\
 </%block>

src/mako/lib/util.mako

@@ -1,5 +1,12 @@
 <%! import util %>\
 
+## source should be ${self.uri}
+## you need to escape the output, using a filter for example
+<%def name="gen_info(source)">\
+DO NOT EDIT !
+This file was generated automatically from '${source}'
+DO NOT EDIT !\
+</%def>
 
 ## This will only work within a substitution, not within python code
 <%def name="to_api_version(v)">\

src/mako/lib/util.py

@@ -35,6 +35,21 @@ def rust_module_doc_comment(s):
 def rust_doc_comment(s):
     return re_linestart.sub('/// ', s)
 
+# rust comment filter
+def rust_comment(s):
+    return re_linestart.sub('// ', s)
+
+# hash-based comment filter
+def hash_comment(s):
+    return re_linestart.sub('# ', s)
+
+# markdown comments
+def markdown_comment(s):
+    nl = ''
+    if not s.endswith('\n'):
+        nl = '\n'
+    return "<!---\n%s%s-->" % (s, nl)
+
 # escape each string in l with "s" and return the new list
 def estr(l):
     return ['"%s"' % i for i in l]