Add "Designs" table to the documentation

doc/design/index.md

@@ -0,0 +1,20 @@
+# Design documents
+
+
+| File                         | Originating Date | Version        | Implementation State | Date             | Version        | Superseded by |
+| ---------------------------- | ---------------- | -------------- | -------------------- | ---------------- | -------------- | ------------- |
+| blob-uuid-1.md               | 2021-03-09       | v0.0.1~15^2~29 |                      |                  |                |               |
+| doi-generation-1.md          | 2021-04-05       | v0.1.0~22^2~14 |                      |                  |                |               |
+| publish-1.md                 | 2021-05-20       | v0.1.0~21^2~6  |                      |                  |                |               |
+| staging-1.md                 | 2021-06-08       | v0.1.0~15^2~3  |                      |                  |                |               |
+| draft-metadata-migration.md  | 2021-08-12       | v0.1.28~8^2~7  |                      |                  |                |               |
+| new-user-questionnaire.md    | 2021-08-12       | v0.1.21~1^2~7  |                      |                  |                |               |
+| garbage-collection-1.md      | 2021-10-11       | v0.2.18~4^2~4  |                      |                  |                |               |
+| zarr-support-3.md            | 2021-10-20       | v0.1.36~5^2~7  |                      |                  |                |               |
+| embargo-full.md              | 2021-12-07       | v0.1.37~4^2~20 |                      |                  |                |               |
+| embargo-mvp.md               | 2021-12-07       | v0.1.37~4^2~20 |                      |                  |                |               |
+| apex-domain-netlify.md       | 2022-04-08       | v0.2.8~2^2     |                      |                  |                |               |
+| deployment-1.md              | 2022-04-13       | v0.2.9~2^2~4   |                      |                  |                |               |
+| asset-paths-1.md             | 2022-09-06       | v0.3.0~11^2~27 |                      |                  |                |               |
+| zarr-performance-redesign.md | 2022-12-19       | v0.3.11~7^2~5  |                      |                  |                |               |
+| s3-trailing-delete.md        | 2023-08-28       | v0.3.52~6^2~3  |                      |                  |                |               |

scripts/produce_md_table_of_files.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+
+import argparse
+from operator import itemgetter
+import subprocess
+
+
+def git_first_commit_date(filename):
+    date_str = subprocess.getoutput(f'git log --follow --format=%ai -- {filename} | tail -n 1')
+    return date_str.split()[0]  # Return only the date portion, ignoring time and timezone
+
+
+def git_describe_contains(commit_hash):
+    result = subprocess.run(
+        ['git', 'describe', '--contains', commit_hash],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else ''
+
+
+def git_first_commit_hash(filename):
+    return subprocess.getoutput(f'git log --pretty=format:%H -- {filename} | tail -n 1')
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Generate a Markdown table for files in a Git repo.'
+    )
+    parser.add_argument('--header', type=str, help='Header for the Markdown file.')
+    parser.add_argument('-o', '--output', type=str, help='Output Markdown file name.')
+    parser.add_argument('files', nargs='+', help='Files to include in the table.')
+    args = parser.parse_args()
+
+    output_lines = []
+    if args.header:
+        output_lines.extend(args.header.split(r'\n'))
+
+    headers = [
+        'File',
+        'Originating Date',
+        'Version',
+        'Implementation State',
+        'Date',
+        'Version',
+        'Superseded by',
+    ]
+    col_widths = [len(h) for h in headers]
+
+    data = []
+
+    for filename in args.files:
+        date = git_first_commit_date(filename)
+        commit_hash = git_first_commit_hash(filename)
+        version = git_describe_contains(commit_hash)
+
+        col_widths[0] = max(col_widths[0], len(filename))
+        col_widths[1] = max(col_widths[1], len(date))
+        col_widths[2] = max(col_widths[2], len(version))
+
+        data.append({'filename': filename, 'date': date, 'version': version})
+
+    col_widths[-3] = col_widths[1]
+    col_widths[-2] = col_widths[2]
+
+    sorted_data = sorted(data, key=itemgetter('date'))
+
+    header_line = '| ' + ' | '.join([h.ljust(w) for h, w in zip(headers, col_widths)]) + ' |'
+    separator_line = '| ' + ' | '.join(['-' * w for w in col_widths]) + ' |'
+
+    output_lines.append(header_line)
+    output_lines.append(separator_line)
+
+    for entry in sorted_data:
+        filename = entry['filename'].ljust(col_widths[0])
+        date = entry['date'].ljust(col_widths[1])
+        version = entry['version'].ljust(col_widths[2])
+        empty_cols = [' ' * w for w in col_widths[3:]]
+        row_line = '| ' + ' | '.join([filename, date, version] + empty_cols) + ' |'
+        output_lines.append(row_line)
+
+    if args.output:
+        with open(args.output, 'w') as f:
+            f.write('\n'.join(output_lines) + '\n')
+    else:
+        print('\n'.join(output_lines))
+
+
+if __name__ == '__main__':
+    main()