Add summary statistics to the coverage report (#5474)

The current implementation of ``sphinx.ext.coverage`` outputs which
methods,classes, and functions are documented.
This commit adds a short summary of this report in terms of
``documented objects / total number of objects``,
both per module and total.

The purpose of this is to support
a currently not mainstream but relevant use-case:
a coverage report on the number of objects that are documented.

By having the statistics on the report or on the stdout,
a regex expression can capture the coverage percentage
(e.g. ``re.search(r'TOTAL.*?([0-9.]{4,6}\%)', d).group(1)``)
and use it e.g. in another report, a status badge, etc.

Two options were added to the configuration to allow a table
to be printed in the report and/or to stdout.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

tests/test_ext_coverage.py

@@ -28,7 +28,7 @@ def test_build(app, status, warning):
     assert 'api.h' in c_undoc
     assert ' * Py_SphinxTest' in c_undoc
 
-    undoc_py, undoc_c = pickle.loads((app.outdir / 'undoc.pickle').read_bytes())
+    undoc_py, undoc_c, py_undocumented, py_documented = pickle.loads((app.outdir / 'undoc.pickle').read_bytes())
     assert len(undoc_c) == 1
     # the key is the full path to the header file, which isn't testable
     assert list(undoc_c.values())[0] == {('function', 'Py_SphinxTest')}
@@ -47,10 +47,24 @@ def test_build(app, status, warning):
 def test_coverage_ignore_pyobjects(app, status, warning):
     app.builder.build_all()
     actual = (app.outdir / 'python.txt').read_text(encoding='utf8')
-    expected = '''Undocumented Python objects
+    expected = '''\
+Undocumented Python objects
 ===========================
+
+Statistics
+----------
+
++----------------------+----------+--------------+
+| Module               | Coverage | Undocumented |
++======================+==========+==============+
+| coverage_not_ignored | 0.00%    | 2            |
++----------------------+----------+--------------+
+| TOTAL                | 0.00%    | 2            |
++----------------------+----------+--------------+
+
 coverage_not_ignored
 --------------------
+
 Classes:
  * Documented -- missing methods: