Initial commit

Signed-off-by: Miguel Ojeda <[email protected]>

Author: ojeda

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install `mdbook`
+        run: |
+          curl --no-progress-meter --location --output mdbook.tar.gz https://github.com/rust-lang/mdBook/releases/download/v0.4.25/mdbook-v0.4.25-x86_64-unknown-linux-gnu.tar.gz
+          echo "2d049e4d0a1ef739a1218cf209c99cdc0d1c66aa43a15e2183770f6e1d333324  mdbook.tar.gz" > mdbook.tar.gz.sha256
+          sha256sum --check --strict mdbook.tar.gz.sha256
+          tar --extract --file mdbook.tar.gz
+
+      - name: Build book
+        run: |
+          ./pre.py
+          ./mdbook build
+          ./post.py
+
+      - name: Deploy to GitHub Pages
+        run: |
+          cd book
+          git init
+          git config user.name CI
+          git config user.email ""
+          git add .
+          git commit -m "Deploy $GITHUB_SHA to branch `gh-pages`"
+          git push --force "https://x-token:${{ secrets.GITHUB_TOKEN }}@github.com/$GITHUB_REPOSITORY" HEAD:gh-pages

.gitignore

@@ -0,0 +1,2 @@
+src/SUMMARY.md
+summary.json

Rust-for-Linux.svg

@@ -0,0 +1,86 @@
+[Rust for Linux](https://rust-for-linux.com)
+
+# The project
+
+  - [Contact](Contact.md)
+  - [Contributing](Contributing.md)
+  - [Branches](Branches.md)
+  - [Rust version policy](Rust-version-policy.md)
+  - [Unstable features](Unstable-features.md)
+  - [Backporting and stable/LTS releases](Backporting-and-stable-LTS-releases.md)
+  - [Industry and academia support](Industry-and-academia-support.md)
+  - [Sponsors](Sponsors.md)
+
+## Subprojects
+
+  - [`klint`](klint.md)
+  - [`pinned-init`](pinned-init.md)
+  - Hidden [The Safe Pinned Initialization Problem](The-Safe-Pinned-Initialization-Problem.md)
+  - Hidden [Ksquirrel](Ksquirrel.md)
+
+## Users
+
+  - [NVMe driver](NVMe-driver.md)
+
+# Links
+
+## Contact
+
+  - [Lore (mailing list archive)](https://lore.kernel.org/rust-for-linux/)
+  - [Zulip (chat)](https://rust-for-linux.zulipchat.com)
+  - [GitHub Organization](https://github.com/Rust-for-Linux)
+
+## Security
+
+  - [Report a security bug](https://docs.kernel.org/admin-guide/security-bugs.html)
+
+## Issue tracking
+
+  - [Issues](https://github.com/Rust-for-Linux/linux/issues)
+  - [Unstable features](https://github.com/Rust-for-Linux/linux/issues/2)
+  - [Good first issues](https://github.com/Rust-for-Linux/linux/contribute)
+
+## Branches
+
+  - [`rust-next`](https://github.com/Rust-for-Linux/linux/tree/rust-next)
+  - [`rust-fixes`](https://github.com/Rust-for-Linux/linux/tree/rust-fixes)
+  - [`rust`](https://github.com/Rust-for-Linux/linux/tree/rust)
+
+## Documentation
+
+  - [Kernel documentation (mainline)](https://docs.kernel.org/rust/index.html)
+  - [Kernel documentation (next)](https://docs.kernel.org/next/rust/index.html)
+  - [`rustdoc` code docs (v6.3-rc2)](https://rust-for-linux.github.io/docs/v6.3-rc2/kernel/)
+  - [`rustdoc` code docs (`rust` 2023-03-13)](https://rust-for-linux.github.io/docs/rust/kernel/)
+  - [`rustdoc` code docs (`pinned-init` v1)](https://rust-for-linux.github.io/docs/pinned-init/kernel/init/)
+  - [`rustdoc` code docs (pre-merge v8 patch)](https://rust-for-linux.github.io/docs/kernel/)
+  - [Out-of-tree module template](https://github.com/Rust-for-Linux/rust-out-of-tree-module)
+
+## Conferences
+
+  - [Kangrejos](https://kangrejos.com)
+  - [Linux Plumbers Conference (LPC)](https://lpc.events)
+  - [Rust MC at LPC 2022](https://lpc.events/event/16/sessions/150/)
+
+## LWN
+
+  - [Rust index](https://lwn.net/Kernel/Index/#Development_tools-Rust)
+  - [Kangrejos index](https://lwn.net/Archives/ConferenceIndex/#Kangrejos)
+
+## Toolchain projects
+
+  - [`rustc_codegen_gcc`](https://github.com/rust-lang/rustc_codegen_gcc)
+  - [Rust GCC](https://rust-gcc.github.io)
+
+## Other trees
+
+  - [Linus' tree](https://git.kernel.org/linus/)
+  - [Stable tree](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/)
+  - [`linux-next` tree](https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/)
+
+## Other resources
+
+  - [Bootlin's Elixir](https://elixir.bootlin.com/linux/latest/source/rust)
+  - [Compiler Explorer](https://godbolt.org/z/W4P36a9h9)
+  - [Rust Playground](https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021)
+  - [Rust `core` docs](https://doc.rust-lang.org/1.62.0/core/)

SUMMARY.md

@@ -0,0 +1,17 @@
+[book]
+title = "Rust for Linux"
+author = "Rust for Linux Contributors"
+description = "Adding support for the Rust language to the Linux kernel"
+language = "en"
+
+[build]
+create-missing = false
+
+[output.html]
+git-repository-url = ""
+edit-url-template = ""
+no-section-label = true
+
+[output.html.fold]
+enable = true
+level = 0

book.toml

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+
+"""Postprocesses the "book".
+"""
+
+import json
+import os
+import pathlib
+import re
+import shutil
+
+def handle_markdown(string):
+    if string.count("`") % 2 != 0:
+        raise RuntimeError("Unbalanced backticks.")
+
+    while True:
+        if "`" not in string:
+            return string
+
+        # Should use `code`, but it requires fixing the general CSS.
+        string = string.replace("`", '<span class="rfl-mono-font">', 1)
+        string = string.replace("`", "</span>", 1)
+
+def process(path, content, html_menu, html_index_toc):
+    # Fix index title (`index.html` and `Rust-for-Linux.html`).
+    content = content.replace("<title>Rust for Linux - Rust for Linux</title>", "<title>Rust for Linux</title>")
+
+    # Fix header.
+    content = content.replace('<link rel="icon" href="favicon.svg">', "")
+    content = content.replace('<link rel="shortcut icon" href="favicon.png">', """
+        <link rel="icon" href="Rust-for-Linux.svg">
+
+        <meta property="og:url" content="https://rust-for-linux.com">
+        <meta property="og:type" content="website">
+        <meta property="og:title" content="Rust for Linux">
+        <meta property="og:description" content="Adding support for the Rust language to the Linux kernel">
+        <meta property="og:image" content="https://rust-for-linux.com/Rust-for-Linux.svg">
+        <script type="application/ld+json">
+        {
+            "@context": "http://schema.org",
+            "@type": "CreativeWork",
+            "name": "Rust for Linux",
+            "description": "Adding support for the Rust language to the Linux kernel",
+            "url": "https://rust-for-linux.com",
+            "image": "https://rust-for-linux.com/Rust-for-Linux.svg"
+        }
+        </script>
+        <style>
+        #logo {
+            display: block;
+            margin-left: auto;
+            margin-right: auto;
+        }
+
+        .rfl-menu-block {
+            text-align: center;
+            font-size: 1.8rem;
+            font-weight: bold;
+        }
+
+        .rfl-mono-font {
+            font-family: var(--mono-font);
+        }
+
+        .rfl-mobile-links {
+            display: none;
+        }
+
+        @media only screen and (max-width: 1080px) {
+            .rfl-mobile-links {
+                display: block;
+            }
+        }
+
+        .chapter li.chapter-item {
+            margin-top: 0.2em !important;
+            margin-left: 1.5em !important;
+        }
+
+        .chapter li.part-title {
+            margin-bottom: -0.3em !important;
+            margin-top: 1em !important;
+        }
+        </style>
+    """)
+
+    # Provide custom menu.
+    content = re.sub(r'<div class="sidebar-scrollbox">.*?</div>', html_menu, content, count=1, flags=re.DOTALL)
+
+    # Append Table of Contents in index (`index.html` and `Rust-for-Linux.html`), as well as
+    # the links for mobile.
+    content = content.replace("<!-- Generated TOC -->", html_index_toc)
+
+    return content
+
+def main():
+    # Read TOC generated by `pre.py`.
+    with open("summary.json", "r", encoding="utf-8") as f:
+        json_summary = json.load(f)
+
+    # Generate menu.
+    html_menu = ""
+    for block_name in json_summary:
+        html_block = ""
+        for section_name in json_summary[block_name]:
+            if section_name != "":
+                html_block += f'<li class="part-title">{section_name}</li>'
+            for (text, link) in json_summary[block_name][section_name]:
+                html_block += f'<li class="chapter-item"><a href="{link}" tabindex="0">{handle_markdown(text)}</a></li>'
+
+        html_menu += f"""
+            <p class="rfl-menu-block">{block_name}</p>
+            <ol class="chapter">{html_block}</ol>
+        """
+
+    html_menu = f"""
+        <div class="sidebar-scrollbox">
+            <a href="/"><img id="logo" src="Rust-for-Linux.svg" alt="Rust for Linux Logo"></a>
+            {html_menu}
+        </div>
+    """
+
+    # Generate TOC for index pages.
+    html_index_toc = {}
+    for block_name in json_summary:
+        html_index_toc[block_name] = ""
+        for section_name in json_summary[block_name]:
+            section_links = ""
+            for (text, link) in json_summary[block_name][section_name]:
+                section_links += f'<li><a href="{link}" tabindex="0">{handle_markdown(text)}</a></li>'
+
+            if section_name != "":
+                html_index_toc[block_name] += f"<h3>{section_name}</h3>\n"
+            if section_links != "":
+                html_index_toc[block_name] += f"<ul>{section_links}</ul>\n"
+
+    html_index_toc = f"""
+        <h2><a class="header" href="#the-project">The project</a></h2>
+        {html_index_toc["The project"]}
+        <div class="rfl-mobile-links">
+            <h2><a class="header" href="#links">Links</a></h2>
+            {html_index_toc["Links"]}
+        </div>
+    """
+
+    # Post-process each `mdbook`-generated file.
+    for path in pathlib.Path().glob("book/**/*.html"):
+        with path.open("r+", encoding="utf-8") as f:
+            new_content = process(path, f.read(), html_menu, html_index_toc)
+            f.seek(0)
+            f.truncate()
+            f.write(new_content)
+
+    # Remove unneeded files.
+    os.remove("book/favicon.svg")
+    os.remove("book/favicon.png")
+
+    # Copy logo.
+    shutil.copyfile("Rust-for-Linux.svg", "book/Rust-for-Linux.svg")
+
+if __name__ == "__main__":
+    main()

post.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0
+
+"""Preprocesses the "book".
+"""
+
+import json
+import pathlib
+import re
+
+def main():
+    md_files_in_summary = set()
+    mdbook_summary = ""
+    json_summary = {}
+    json_current_block = None
+    json_current_section = None
+
+    with open("SUMMARY.md", "r", encoding="utf-8") as f:
+        for line in f:
+            # Blank lines.
+            if line == "\n":
+                continue
+
+            # The index/root link.
+            if line == "[Rust for Linux](https://rust-for-linux.com)\n":
+                md_files_in_summary.add("Rust-for-Linux.md")
+                mdbook_summary += "[Rust for Linux](Rust-for-Linux.md)\n"
+                continue
+
+            # Blocks.
+            match = re.match(r"^# (.*)$", line)
+            if match:
+                json_current_block = match[1]
+                json_current_section = ""
+                json_summary[json_current_block] = {}
+                json_summary[json_current_block][json_current_section] = []
+                continue
+
+            # Titles.
+            match = re.match(r"^## (.*)$", line)
+            if match:
+                json_current_section = match[1]
+                json_summary[json_current_block][json_current_section] = []
+                continue
+
+            # Hidden links.
+            match = re.match(r"^  - Hidden \[(.*)\]\((.*)\.md\)$", line)
+            if match:
+                md_files_in_summary.add(f"{match[2]}.md")
+                mdbook_summary += f"  - [{match[1]}]({match[2]}.md)\n"
+                continue
+
+            # Chapter links.
+            match = re.match(r"^  - \[(.*)\]\((.*)\.md\)$", line)
+            if match:
+                md_files_in_summary.add(f"{match[2]}.md")
+                mdbook_summary += line
+                json_summary[json_current_block][json_current_section].append((match[1], f"{match[2]}.html"))
+                continue
+
+            # External links.
+            match = re.match(r"^  - \[(.*)\]\((.*)\)$", line)
+            if match:
+                json_summary[json_current_block][json_current_section].append((match[1], match[2]))
+                continue
+
+            raise RuntimeError("Unknown syntax")
+
+    md_files_in_src = set(str(path.relative_to("src")) for path in pathlib.Path("src").glob("**/*.md"))
+    md_files_in_src.discard("SUMMARY.md")
+    if md_files_in_summary != md_files_in_src:
+        raise AssertionError("Unmatched files in generated `SUMMARY.md` vs. `src` folder")
+
+    with open("src/SUMMARY.md", "w", encoding="utf-8") as f:
+        f.write(mdbook_summary)
+
+    with open("summary.json", "w", encoding="utf-8") as f:
+        json.dump(json_summary, f)
+
+if __name__ == "__main__":
+    main()