doc/api.txt: Merge with api-funcs.txt

It's important that users have a single, easy-to-remember place for
reading about the API. So this commit changes gen_api_vimdoc.py so that
the generated section is appended to api.txt instead of creating
a separate document.

Also remove the section numbering and ToC: it's a maintenance cost, and
it will be unnecessary when #5169 is integrated.

scripts/gen_api_vimdoc.py

@@ -38,12 +38,9 @@ import subprocess
 
 from xml.dom import minidom
 
-# Text at the top of the doc file.
-preamble = '''
-Note: This documentation is generated from Neovim's API source code.
-'''
-
-doc_filename = 'api-funcs.txt'
+doc_filename = 'api.txt'
+# String used to find the start of the generated part of the doc.
+section_start_token = '*api-global*'
 
 # Section name overrides.
 section_name = {
@@ -376,6 +373,19 @@ def parse_source_xml(filename):
     return '\n\n'.join(functions), '\n\n'.join(deprecated_functions)
 
 
+def delete_lines_below(filename, tokenstr):
+    """Deletes all lines below the line containing `tokenstr`, the line itself,
+    and one line above it.
+    """
+    lines = open(filename).readlines()
+    i = 0
+    for i, line in enumerate(lines, 1):
+        if tokenstr in line:
+            break
+    i = max(0, i - 2)
+    with open(filename, 'wt') as fp:
+        fp.writelines(lines[0:i])
+
 def gen_docs(config):
     """Generate documentation.
 
@@ -387,7 +397,6 @@ def gen_docs(config):
     if p.returncode:
         sys.exit(p.returncode)
 
-    title_length = 0
     sections = {}
     sep = '=' * text_width
 
@@ -425,26 +434,13 @@ def gen_docs(config):
                     name = section_name.get(filename, name)
                     title = '%s Functions' % name
                     helptag = '*api-%s*' % name.lower()
-                    title_length = max(title_length, len(title))
                     sections[filename] = (title, helptag, doc)
 
     if not sections:
         return
 
-    title_left = '*%s*' % doc_filename
-    title_center = 'Neovim API Function Reference'
-    title_right = '{Nvim}'
-    margin = max(len(title_left), len(title_right))
-    head = (title_left.ljust(margin) +
-            title_center.center(text_width - margin * 2) +
-            title_right.rjust(margin)) + '\n'
-
-    head += '\n%s\n\n' % doc_wrap(preamble, width=text_width)
-    head += 'Contents:\n\n'
-
     docs = ''
 
-    title_length += len(str(len(section_order))) + 2
     i = 0
     for filename in section_order:
         if filename not in sections:
@@ -453,9 +449,6 @@ def gen_docs(config):
 
         i += 1
         docs += sep
-        title = '%d. %s' % (i, title)
-        head += (title.ljust(title_length) + '  ' +
-                 helptag.replace('*', '|') + '\n')
         docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
         docs += section_doc
         docs += '\n\n\n'
@@ -465,21 +458,17 @@ def gen_docs(config):
         for title, helptag, section_doc in sections.values():
             i += 1
             docs += sep
-            title = '%d. %s' % (i, title)
-            head += (title.ljust(title_length) + '  ' +
-                     helptag.replace('*', '|') + '\n')
             docs += '\n%s%s' % (title, helptag.rjust(text_width - len(title)))
             docs += section_doc
             docs += '\n\n\n'
 
-    docs = '%s\n%s' % (head, docs)
     docs = docs.rstrip() + '\n\n'
     docs += ' vim:tw=78:ts=8:ft=help:norl:'
 
     doc_file = os.path.join(base_dir, 'runtime/doc', doc_filename)
-    with open(doc_file, 'wb') as fp:
+    delete_lines_below(doc_file, section_start_token)
+    with open(doc_file, 'ab') as fp:
         fp.write(docs.encode('utf8'))
-
     shutil.rmtree(out_dir)