ENH: include root index.html in --html output

pdoc/cli.py

@@ -82,6 +82,11 @@
     help="The directory to output generated HTML/markdown files to "
          "(default: ./html for --html).",
 )
+aa(
+    "--html-index",
+    action="store_true",
+    help="Make a top-level index.html listing all the documented packages."
+)
 aa(
     "--html-no-source",
     action="store_true",
@@ -487,6 +492,25 @@ def docfilter(obj, _filters=args.filter.strip().split(',')):
             # Two blank lines between two modules' texts
             sys.stdout.write(os.linesep * (1 + 2 * int(module != modules[-1])))
 
+    if args.html and args.html_index:
+        # Add the root index.html at the top level.
+        # The template expects `modules` to be Tuples of (name, docstring).
+        module_tuples = sorted((module.name, module.docstring)
+                               for module in modules)
+        index_text = pdoc._render_template('/html.mako',
+                                           modules=module_tuples,
+                                           **template_config)
+        index_file = path.join(args.output_dir, 'index.html')
+        try:
+            with open(index_file, 'w+', encoding='utf-8') as w:
+                w.write(index_text)
+        except Exception:
+            try:
+                os.unlink(index_file)
+            except Exception:
+                pass
+            raise
+
 
 if __name__ == "__main__":
     main(parser.parse_args())