Merge pull request #3388 from ehuss/generate-subpages

Add support for rfc subchapters

Author: joshtriplett

.github/workflows/deploy.yml

@@ -14,11 +14,11 @@ jobs:
     - name: Install mdbook
       run: |
         mkdir mdbook
-        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.21/mdbook-v0.4.21-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
+        curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.4.26/mdbook-v0.4.26-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
         echo `pwd`/mdbook >> $GITHUB_PATH
     - name: Generate Book
       run: |
-        ./generate-book.sh
+        ./generate-book.py
     - name: Deploy GitHub Pages
       run: |
         git worktree add gh-pages gh-pages

generate-book.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+
+"""
+This auto-generates the mdBook SUMMARY.md file based on the layout on the filesystem.
+
+This generates the `src` directory based on the contents of the `text` directory.
+
+Most RFCs should be kept to a single chapter. However, in some rare cases it
+may be necessary to spread across multiple pages. In that case, place them in
+a subdirectory with the same name as the RFC. For example:
+
+    0123-my-awesome-feature.md
+    0123-my-awesome-feature/extra-material.md
+
+It is recommended that if you have static content like images that you use a similar layout:
+
+    0123-my-awesome-feature.md
+    0123-my-awesome-feature/diagram.svg
+
+The chapters are presented in sorted-order.
+"""
+
+import os
+import shutil
+import subprocess
+
+def main():
+    if os.path.exists('src'):
+        # Clear out src to remove stale links in case you switch branches.
+        shutil.rmtree('src')
+    os.mkdir('src')
+
+    for path in os.listdir('text'):
+        symlink(f'../text/{path}', f'src/{path}')
+    symlink('../README.md', 'src/introduction.md')
+
+    with open('src/SUMMARY.md', 'w') as summary:
+        summary.write('[Introduction](introduction.md)\n\n')
+        collect(summary, 'text', 0)
+
+    subprocess.call(['mdbook', 'build'])
+
+def collect(summary, path, depth):
+    entries = [e for e in os.scandir(path) if e.name.endswith('.md')]
+    entries.sort(key=lambda e: e.name)
+    for entry in entries:
+        indent = '    '*depth
+        name = entry.name[:-3]
+        link_path = entry.path[5:]
+        summary.write(f'{indent}- [{name}]({link_path})\n')
+        maybe_subdir = os.path.join(path, name)
+        if os.path.isdir(maybe_subdir):
+            collect(summary, maybe_subdir, depth+1)
+
+def symlink(src, dst):
+    if not os.path.exists(dst):
+        os.symlink(src, dst)
+
+if __name__ == '__main__':
+    main()

generate-book.sh

@@ -53,7 +53,7 @@ explicitly re-proposed through the project group process detailed in this RFC.
 This is a high level overview of the complete process of a project group.
 
 <p align="center">
-    <img src="../resources/project-group-workflow.svg"
+    <img src="2856-project-groups/project-group-workflow.svg"
         alt="A flow diagram showing each step of a project group"
         height="800px">
     <p align="center">Figure 1. Project Group Lifecycle</p>