doc: autogenerate a list of authors and hall of fame

This adds a build-time option to automatically generate a list of
authors from git history, and includes it in the documentation by
reading the output from git in a Sphinx extension. When git isn't
available or the project source doesn't appear to be a git checkout, the
list is not generated and gracefully replaced with a message explaining
its absence.

Change-Id: I1e9634a90e84262aafd80590deba9875f4b71a3c
Signed-off-by: Peter Marheine <pmarheine@chromium.org>
Reviewed-on: https://review.coreboot.org/c/flashrom/+/86350
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Anastasia Klimchuk <aklm@chromium.org>

doc/_ext/.gitignore

@@ -0,0 +1,2 @@
+# Python bytecode cache generated on module import
+/__pycache__/

doc/_ext/flashrom_authors.py

@@ -0,0 +1,82 @@
+from docutils import nodes
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+
+if TYPE_CHECKING:
+    from sphinx.util.typing import ExtensionMetadata
+
+
+class FlashromAuthorsDirective(SphinxDirective):
+    required_arguments = 1
+    has_content = True
+
+    def make_table(self, list_file: Path):
+        body = nodes.tbody()
+        with list_file.open("r") as f:
+            for line in f:
+                count, _, name = line.strip().partition("\t")
+
+                body += nodes.row(
+                    "",
+                    nodes.entry("", nodes.paragraph(text=name)),
+                    nodes.entry("", nodes.paragraph(text=count)),
+                )
+
+        return nodes.table(
+            "",
+            nodes.tgroup(
+                "",
+                nodes.colspec(colname="name"),
+                nodes.colspec(colname="count"),
+                nodes.thead(
+                    "",
+                    nodes.row(
+                        "",
+                        nodes.entry("", nodes.paragraph(text="Name")),
+                        nodes.entry("", nodes.paragraph(text="Number of changes")),
+                    ),
+                ),
+                body,
+                cols=2,
+            ),
+        )
+
+    def make_placeholder(self, contents):
+        return nodes.admonition(
+            "",
+            nodes.title("", text="List not available"),
+            *contents,
+        )
+
+    def run(self) -> list[nodes.Node]:
+        config = self.config.flashrom_authors_list_files
+
+        source_name = self.arguments[0]
+        list_file = (config or {}).get(source_name)
+        if list_file is None:
+            if config is not None:
+                available_names = ','.join(config.keys())
+                raise self.error(
+                    'Undefined authors list file: "{}" (available names: {})'.format(
+                        source_name, available_names
+                    )
+                )
+            container = nodes.Element()
+            self.state.nested_parse(self.content, 0, container)
+            return [self.make_placeholder(container.children)]
+        else:
+            return [self.make_table(Path(list_file))]
+
+
+def setup(app: Sphinx) -> 'ExtensionMetadata':
+    app.add_config_value(
+        "flashrom_authors_list_files", default=None, rebuild="html", types=[dict]
+    )
+    app.add_directive("flashrom-authors", FlashromAuthorsDirective)
+
+    return {
+        "version": "1",
+    }

doc/about_flashrom/hall_of_fame.rst

@@ -0,0 +1,57 @@
+============
+Hall of Fame
+============
+
+This is the flashrom project's hall of fame, where we credit everybody who
+has contributed to flashrom's code in the past.
+
+Based on the Git history (dating back to 2002!), this page separately lists all
+:ref:`authors <authors>` and :ref:`reviewers <reviewers>` where each line
+lists a person's name and how many commits they are credited for. [#svn]_
+
+flashrom is alive and running because of you all, the people who during all
+these years (and decades!) give their time, energy, knowledge, and a piece of
+their heart to flashrom. The project is what we all are creating together.
+
+**Thank you everyone so much!**
+
+.. _authors:
+
+Authors
+=======
+
+The people listed here are those credited as the author or a co-author (as
+in ``Co-authored-by`` or ``Co-developed-by``) of at least one Git commit in
+flashrom.
+
+.. flashrom-authors:: authors
+
+  This copy of the flashrom documentation was built without
+  generating the list of authors. To generate it, ensure
+  the :code:`generate_authors_list`
+  :ref:`Meson option <meson_configuration>` is enabled when
+  building.
+
+.. _reviewers:
+
+Reviewers
+=========
+
+The people listed here are those credited as a reviewer (``Reviewed-by``)
+of at least one Git commit in flashrom.
+
+We very much appreciate flashrom code reviews; you can read more about it
+in our :ref:`code review documentation <support-code-reviews>`.
+
+.. flashrom-authors:: reviewers
+
+  This copy of the flashrom documentation was built without
+  generating the list of reviewers. To generate it, ensure
+  the :code:`generate_authors_list`
+  :ref:`Meson option <meson_configuration>` is enabled when
+  building.
+
+.. [#svn] Data for contributions prior to 2017 may be inaccurate or missing,
+  because flashrom used SVN rather than Git prior to then and old metadata might
+  not be in a format that is understood by the scripts that automatically generate
+  this page.

doc/about_flashrom/index.rst

@@ -5,5 +5,6 @@ About flashrom
     :maxdepth: 1
 
     team
+    hall_of_fame
     code_of_conduct
     privacy_policy

doc/classic_cli_manpage.rst

@@ -1565,14 +1565,12 @@ Please see the individual files.
 AUTHORS
 -------
 
-Andrew Morgan, Anastasia Klimchuk, Carl-Daniel Hailfinger, Claus Gindhart, David Borg, David Hendricks, Dominik Geyer,
+More than 350 authors have contributed to Flashrom over its life. Each individual
-Edward O'Callaghan, Eric Biederman, Giampiero Giancipoli, Helge Wagner, Idwer Vollering, Joe Bao, Joerg Fischer,
+is credited in the `hall of fame <https://flashrom.org/about_flashrom/hall_of_fame.html>`_,
-Joshua Roys, Kyösti Mälkki, Luc Verhaegen, Li-Ta Lo, Mark Marshall, Markus Boas, Mattias Mattsson, Michael Karcher,
+or author metadata can be found in the git history.
-Nikolay Petukhov, Patrick Georgi, Peter Lemenkov, Peter Stuge, Reinder E.N. de Haan, Ronald G. Minnich, Ronald Hoogenboom,
-Sean Nelson, Stefan Reinauer, Stefan Tauner, Stefan Wildemann, Stephan Guilloux, Steven James, Urja Rannikko, Uwe Hermann,
-Wang Qingpei, Yinghai Lu and others, please see the **flashrom** git history for details.
 
 All still active authors can be reached via `the mailing list <flashrom\@flashrom.org>`_.
 
-This manual page was written by `Uwe Hermann <uwe\@hermann-uwe.de>`_, Carl-Daniel Hailfinger, Stefan Tauner and others.
+This manual page was written by `Uwe Hermann <uwe\@hermann-uwe.de>`_,
-It is licensed under the terms of the GNU GPL (version 2 or later).
+Carl-Daniel Hailfinger, Stefan Tauner and others.  It is licensed under the
+terms of the GNU GPL (version 2 or later).

doc/collect-authors.sh

@@ -0,0 +1,39 @@
+#!/bin/sh
+
+if [ $# -ne 3 ]
+then
+    echo "Wrong number of arguments. Usage: $0 [authors|reviewers] outfile git_dir" >&2
+    exit 1
+fi
+
+case "$1" in
+    authors)
+        GROUP_ARGS="--group=author --group=trailer:Co-Authored-by --group=trailer:Co-Developed-by"
+        ;;
+    reviewers)
+        GROUP_ARGS="--group=trailer:Reviewed-by"
+        ;;
+    *)
+        echo "Unknown contributor kind: \"$1\"" >&2
+        exit 1
+        ;;
+esac
+OUTFILE="$2"
+# GIT_DIR is passed explicitly so we never need to guess where
+# the source directory is. It may be somewhere entirely different
+# from where meson is running us.
+GIT_DIR="$3"
+
+if ! command -v git >/dev/null
+then
+    echo "git not available" >&2
+    exit 1
+fi
+
+if [ ! -d "$GIT_DIR" ]
+then
+    echo "GIT_DIR ($GIT_DIR) does not exist" >&2
+    exit 1
+fi
+
+git --no-pager --git-dir="$GIT_DIR" shortlog --summary --numbered $GROUP_ARGS HEAD > "$OUTFILE"

doc/conf.py

@@ -3,7 +3,13 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-import os
+import sys
+
+from pathlib import Path
+
+
+sys.path.append(str(Path('_ext').resolve()))
+
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
@@ -18,7 +24,8 @@ author = 'The flashrom authors'
 master_doc = 'index' # this is needed for old versions
 
 extensions = [
-    'sphinx.ext.todo'
+    'sphinx.ext.todo',
+    'flashrom_authors'
 ]
 
 #templates_path = ['_templates']

doc/dev_guide/building_from_source.rst

@@ -216,8 +216,11 @@ libpayload
     .. todo:: Add building instructions for libpayload
 
 
+.. _meson_configuration:
+
 Configuration
 -------------
+
 In the flashrom repository run::
 
     meson setup [builtin options] [flashrom options] <builddir>

doc/how_to_support_flashrom.rst

@@ -39,6 +39,8 @@ for examples on how the dev process works.
 
 For some types of contributions we have more detailed guidelines, check the list :doc:`/contrib_howtos/index`.
 
+.. _support-code-reviews:
+
 Code reviews
 ============
 

doc/meson.build

@@ -1,6 +1,6 @@
-
 sphinx = find_program('sphinx-build', native : true, required : get_option('man-pages').enabled() or get_option('documentation').enabled())
 sphinx_wrapper = meson.current_source_dir() / 'sphinx-wrapper.sh'
+collect_authors = meson.current_source_dir() / 'collect-authors.sh'
 
 man_pages = [
   'flashrom.8'
@@ -24,9 +24,67 @@ if sphinx.found()
   endif
 
   if get_option('documentation').auto() or get_option('documentation').enabled()
+
+    with_authors_list = get_option('generate_authors_list')
+    git = find_program('git', native : true, required : with_authors_list)
+    git_dir = meson.project_source_root() / '.git'
+
+    # When with_authors_list is requested, unsatisfied requirements are an error.
+    if with_authors_list.enabled()
+      if not git.found()
+        error('generate_authors_list was force-enabled but git is not available')
+      endif
+      if not fs.is_dir(git_dir)
+        error('generate_authors_list was force-enabled but a .git directory was not found in the source tree')
+      endif
+    endif
+
+    if (
+      (with_authors_list.enabled() or with_authors_list.auto())
+      and git.found() and fs.is_dir(git_dir)
+    )
+      # If requirements are met and authors list is allowed, generate it.
+      authors_lst = custom_target(
+        'authors_lst',
+        output : 'authors.lst',
+        command : [collect_authors, 'authors', '@OUTPUT0@', git_dir],
+      )
+      reviewers_lst = custom_target(
+        'reviewers_lst',
+        output : 'reviewers.lst',
+        command : [collect_authors, 'reviewers', '@OUTPUT0@', git_dir],
+      )
+      authors_list_options = [
+        '-Dflashrom_authors_list_files.authors=' + authors_lst.full_path(),
+        '-Dflashrom_authors_list_files.reviewers=' + reviewers_lst.full_path(),
+      ]
+      doc_depends = [authors_lst, reviewers_lst]
+    else
+      # Disabled or prerequisites not met. Continue without the authors list.
+      # Checks earlier in this file will raise an error if the feature is enabled
+      # but the prerequisites aren't met.
+      authors_list_options = []
+      doc_depends = []
+
+      if with_authors_list.auto()
+        # Explain what wasn't satisfied to help the user understand why
+        # the authors list is missing.
+        if not git.found()
+          message('git not found; will not generate authors list')
+        elif not fs.is_dir(git_dir)
+          message('.git directory not found in project; will not generate authors list')
+        endif
+      endif
+    endif
+
     custom_target(
       'documentation',
-      command : [sphinx, '-b', 'html', '-q', '-d', '@PRIVATE_DIR@', '-Drelease=' + flashrom_version,'@CURRENT_SOURCE_DIR@', '@OUTDIR@/html'],
+      command : [
+        sphinx, '-b', 'html', '-q', '-d', '@PRIVATE_DIR@',
+        '-Drelease=' + flashrom_version,
+        '@CURRENT_SOURCE_DIR@', '@OUTDIR@/html'
+      ] + authors_list_options,
+      depends : doc_depends,
       build_always_stale : true, # sphinx handles rebuilds
       output  : 'html',
       install : true,

doc/release_notes/devel.rst

@@ -35,3 +35,19 @@ New features
 -------------------------------------------
 
 See :doc:`/classic_cli_manpage` for details.
+
+Hall of Fame added to documentation
+-----------------------------------
+
+The flashrom HTML documentation (and web site) now includes an
+automatically-generated list of historical contributors, to acknowledge
+everybody who has made flashrom into what it is:
+:doc:`../about_flashrom/hall_of_fame`.
+
+When building the documentation, the ``generate_authors_list`` Meson option will
+cause the lists to be generated, requiring a runnable copy of Git on the system
+and that the source tree being built is a Git working copy. If those
+requirements are not satisfied or the option is disabled, the authors lists will
+be replaced with placeholders unless the ``generate_authors_list`` option is set
+to ``enabled`` in which case the build will fail if the requirements are not
+satisfied.

meson_options.txt

@@ -19,6 +19,7 @@ option('programmer', type : 'array', value : ['auto'], choices : [
 option('llvm_cov', type : 'feature', value : 'disabled', description : 'build for llvm code coverage')
 option('man-pages', type : 'feature', value : 'auto', description : 'build the man-page for classic_cli')
 option('documentation', type : 'feature', value : 'auto', description : 'build the html documentation')
+option('generate_authors_list', type : 'feature', value : 'auto', description : 'include automatically-generated lists of authors in the HTML documentation')
 option('ni845x_search_path', type : 'string', value : 'C:\Program Files (x86)\National Instruments\Ni-845x\MS Visual C',
        description : 'Path to search for the proprietary ni845x library and header (32-bit Windows only)')
 option('delay_minimum_sleep_us', type : 'integer', min : 0, value : 100,