Port the generation of template language function reference to new code

Note that in other documentation, the function reference can be linked
to using

:ref:`ff_function_name`  for example, :ref:`ff_add`

manual/conf.py

@@ -43,7 +43,7 @@ extensions = ['sphinx.ext.autodoc', 'custom', 'sidebar_toc', 'sphinx.ext.viewcod
 templates_path = ['templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = {'.rst': 'restructuredtext'}
 
 # The master toctree document.
 master_doc = 'index' if tags.has('online') else 'simple_index'  # noqa

manual/template_ref_generate.py

@@ -5,7 +5,6 @@
 __license__   = 'GPL v3'
 __copyright__ = '2008, Kovid Goyal <kovid at kovidgoyal.net>'
 
-import re
 from collections import defaultdict
 
 PREAMBLE = '''\
@@ -27,20 +26,6 @@ insufficient. The functions are arranged in logical groups by type.
 
 '''
 
-CATEGORY_TEMPLATE = '''\
-{category}
-{dashes}
-
-'''
-
-FUNCTION_TEMPLATE = '''\
-{fs}
-{hats}
-
-.. autoclass:: {cn}
-
-'''
-
 POSTAMBLE = '''\
 
 API of the Metadata objects
@@ -66,33 +51,34 @@ functions.
 
 
 def generate_template_language_help(language):
+    from tempfile import TemporaryDirectory
+
+    from calibre.db.legacy import LibraryDatabase
+    from calibre.utils.ffml_processor import FFMLProcessor
     from calibre.utils.formatter_functions import formatter_functions
-    pat = re.compile(r'\)`{0,2}\s*-{1,2}')
-
-    funcs = defaultdict(dict)
-
-    for func in formatter_functions().get_builtins().values():
-        class_name = func.__class__.__name__
-        func_sig = getattr(func, 'doc')
-        m = pat.search(func_sig)
-        if m is None:
-            print('No signature for template function ', class_name)
-            continue
-        func_sig = func_sig[:m.start()+1].strip('`')
-        func_cat = getattr(func, 'category')
-        funcs[func_cat][func_sig] = class_name
 
     output = PREAMBLE.format(language)
-    cats = sorted(funcs.keys())
-    for cat in cats:
-        output += CATEGORY_TEMPLATE.format(category=cat, dashes='-'*len(cat))
-        entries = [k for k in sorted(funcs[cat].keys())]
-        for entry in entries:
-            output += FUNCTION_TEMPLATE.format(fs=entry, cn=funcs[cat][entry],
-                                               hats='^'*len(entry))
 
-    output += POSTAMBLE
-    return output
+    with TemporaryDirectory() as tdir:
+        db = LibraryDatabase(tdir) # needed to load formatter_funcs
+        ffml = FFMLProcessor()
+        all_funcs = formatter_functions().get_builtins()
+        categories = defaultdict(dict)
+        for name, func in all_funcs.items():
+            category = func.category
+            categories[category][name] = func
+        for cat_name in sorted(categories):
+            output += cat_name + '\n'
+            output += ('-' * (4*len(cat_name))) + '\n\n'
+            for name in sorted(categories[cat_name]):
+                func = categories[cat_name][name]
+                output += f"\n\n.. _ff_{name}:\n\n{name}\n{'^'*len(name)}\n\n"
+                output += f'.. class:: {func.__class__.__name__}\n\n'
+                output += ffml.document_to_rst(func.doc, name)
+            output += '\n\n'
+        del db
+
+    return output + POSTAMBLE
 
 if __name__ == '__main__':
     generate_template_language_help()