Add RFC book (#1)

.github/download-rfc-prs.js

@@ -0,0 +1,43 @@
+const fs = require('fs')
+
+module.exports = async ({github, context}) => {
+    const owner = 'polkadot-fellows'
+    const repo = 'RFCs'
+    const prs = await github.paginate(github.rest.pulls.list, {owner, repo, state: 'open'})
+
+    /*
+      The open PRs are potential proposed RFCs.
+      We iterate over them and filter those that include a new RFC markdown file.
+    */
+    for (const pr of prs) {
+      const addedMarkdownFiles = (
+        await github.rest.pulls.listFiles({
+          owner, repo,
+          pull_number: pr.number,
+        })
+      ).data.filter(
+        (file) => file.status === "added" && file.filename.startsWith("text/") && file.filename.includes(".md"),
+      );
+      if (addedMarkdownFiles.length !== 1) continue;
+      const [rfcFile] = addedMarkdownFiles;
+
+      /*
+        The git patches are the only way to get the RFC contents without additional API calls.
+        The alternative would be to download the file contents, one call per PR.
+        The patch in this object is not a full patch with valid syntax, so we need to modify it a bit - add a header.
+      */
+      // This header will cause the patch to create a file in patches/text/*.md.
+      const patch = `--- /dev/null\n+++ b/patches/${rfcFile.filename}\n` + rfcFile.patch + "\n"
+      fs.writeFileSync(`patches/${rfcFile.filename}.patch`, patch)
+
+      /*
+        We want to link the proposed RFCs to their respective PRs.
+        While we have it, we add a link to the source to markdown files.
+        Later, we will append the text of the RFCs to those files.
+      */
+      fs.writeFileSync(
+        `mdbook/src/proposed/${rfcFile.filename.replace('text/','')}`,
+        `[(source)](${pr.html_url})\n\n`
+      )
+    }
+}

.github/workflows/mdbook.yml

@@ -0,0 +1,65 @@
+name: mdBook
+
+on:
+  push:
+    branches:
+      - main
+      - rzadp/rfc-book
+  # schedule:
+  #   - cron: "0 0 * * *" # Once a day
+
+jobs:
+  mdbook:
+    runs-on: ubuntu-latest
+    permissions:
+      # For writing to gh-pages branch.
+      contents: write
+    steps:
+      - name: Checkout this repo
+        uses: actions/checkout@v3
+
+      - name: Precreate necessary directories
+        run: |
+          mkdir -p mdbook/src/proposed
+          mkdir -p patches/text
+          
+      - name: Download all proposed RFCs (open PRs)
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const script = require('.github/download-rfc-prs.js')
+            console.log(await script({github, context}))
+
+        # Create the proposed RFC markdown files from the patches gather in the step above.
+      - run: |
+          # We execute the patches, which results in markdown files created in patches/text/*.md
+          for f in ./patches/text/*.patch;
+          do
+            [ -e "$f" ] || break
+            git apply $f
+          done;
+
+          cd patches/text/
+          # We go over the created markdown files and move them for mdbook to pick up.
+          for f in *.md
+          do
+            [ -e "$f" ] || break
+            # We append the contents - because the links to source already exist there at this point.
+            cat $f >> "../../mdbook/src/proposed/$f"
+          done;
+      - name: Setup mdBook binary
+        uses: peaceiris/actions-mdbook@adeb05db28a0c0004681db83893d56c0388ea9ea # v1.2.0
+        with:
+          mdbook-version: '0.4.35'
+        # This will: 
+        # - gather the proposed RFCs (constructed in the steps above).
+        # - gather the approved RFCs (they exist in this repo in text/ directory)
+        # - generate the mdbook out of it
+      - name: Generate the mdbook
+        run: mdbook/book.sh
+
+      - name: Deploy to github pages
+        uses: peaceiris/actions-gh-pages@373f7f263a76c20808c831209c920827a82a2847 # v3.9.3
+        with:
+          publish_dir: ./mdbook/book
+          github_token: ${{ secrets.GITHUB_TOKEN }}

mdbook/.gitignore

@@ -0,0 +1,4 @@
+approved/
+proposed/
+book/
+SUMMARY.md

mdbook/SUMMARY_preface.md

@@ -0,0 +1,8 @@
+# Summary
+
+[Introduction](introduction.md)
+
+---
+
+# Approved
+

mdbook/book.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd $(dirname ${BASH_SOURCE[0]})
+
+# This script will gatcher two sets of markdown files:
+# - approved RFCs (already merged)
+# - proposed RFCs (pending PRs)
+mkdir -p src/{approved,proposed}
+
+# mdBook relies on the creation of a special SUMMARY.md file
+# https://rust-lang.github.io/mdBook/format/summary.html
+cat SUMMARY_preface.md > src/SUMMARY.md
+
+# Copy the approved RFCs markdown files, first adding a source link at the top.
+cd ../text/
+for f in *.md;
+do
+  [ -e "$f" ] || break
+  echo -e "[(source)](https://github.com/polkadot-fellows/RFCs/blob/main/text/$f)\n" > "../mdbook/src/approved/$f"
+  cat "$f" >> "../mdbook/src/approved/$f"
+done
+cd -
+
+# This will append links to all RFCs into the SUMMARY.md,
+# forming a sidebar of all contents.
+append_rfc_to_summary () {
+  local file="$1"
+  local title=$(head -n 3 $file | grep '# ') # Grab the title from the contents of the file
+  local title=${title#\# } # Remove the "# " prefix
+  local path=${file#./src/} # Relative path, without the src prefix (format required by mdbook)
+  echo "- [$title]($path)" >> src/SUMMARY.md;
+}
+
+for f in ./src/approved/*.md;
+do
+  [ -e "$f" ] || break
+  append_rfc_to_summary "$f"
+done
+
+# Add a section header, and start adding proposed RFCs.
+echo -e "\n---\n\n# Proposed\n\n" >> src/SUMMARY.md
+
+for f in ./src/proposed/*.md;
+do
+  [ -e "$f" ] || break
+  append_rfc_to_summary "$f"
+done
+
+echo -e "Preview of the generated SUMMARY.md:\n"
+cat src/SUMMARY.md
+
+rm -rf ./book/
+mdbook build --dest-dir ./book/

mdbook/book.toml

@@ -0,0 +1,18 @@
+[book]
+title = "Polkadot Fellowship RFCs"
+description = "An online book of RFCs approved or proposed within the Polkadot Fellowship."
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+additional-css = ["theme/polkadot.css"]
+default-theme = "polkadot"
+preferred-dark-theme = "polkadot"
+copy-fonts = true
+no-section-label = true
+
+[output.html.font]
+enable = true
+woff = true

mdbook/src/introduction.md

@@ -0,0 +1,8 @@
+<p><img width="30%" src="images/Polkadot_Logo_Horizontal_Pink_Black.svg" alt="Polkadot logo" /></p>
+
+# Introduction
+
+This book contains the Polkadot Fellowship Requests for Comments (RFCs)
+detailing proposed changes to the technical implementation of the Polkadot network.
+
+<p><img width="2%" src="images/github-mark.svg" alt="GitHub logo" />&nbsp;<a href="https://github.com/polkadot-fellows/RFCs/">polkadot-fellows/RFCs</a></p>

mdbook/theme/fonts/fonts.css

@@ -0,0 +1,42 @@
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-ExtraLight.woff2) format("woff2");
+  font-weight:200;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Light.woff2) format("woff2");
+  font-weight:300;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Regular.woff2) format("woff2");
+  font-weight:400;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Medium.woff2) format("woff2");
+  font-weight:500;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Bold.woff2) format("woff2");
+  font-weight:700;
+  font-style:normal;
+  font-display:block
+}
+@font-face {
+  font-family:Unbounded;
+  src:url(./Unbounded-Black.woff2) format("woff2");
+  font-weight:900;
+  font-style:normal;
+  font-display:block
+}