Merge branch '📝-common' into 🦆

Author: yvt

.github/workflows/doc.yml

@@ -18,16 +18,26 @@ jobs:
 
       - name: Install dependencies (Linux)
         run: .github/scripts/install-deno.sh
+      - name: Set rustdoc flags
+        run: |
+          # [ref:doc_global_styling]
+          echo "RUSTDOCFLAGS=--html-in-header `pwd`/src/r3/src/common.md" >> $GITHUB_ENV
 
       - name: Build Documentation
         uses: actions-rs/cargo@v1
         with:
           command: doc
+          # Documentate all published packages with all features enabled [tag:doc_all_features]
           args: -p r3_port_std -p r3_port_arm -p r3_port_arm_m -p r3_port_riscv -p r3_support_rp2040 -p r3_support_rza1 -p r3_portkit -p r3_kernel -p r3 -p r3_core --all-features
 
       - name: Replace the non-local crate documentation with redirect pages to docs.rs
         run: deno run -A scripts/externalize-non-local-docs.ts -y
 
+      - name: Check the generated documentation
+        run: |
+          # Don't fail the pipeline on errors because they are mostly minor
+          deno run --allow-read scripts/check-doc.ts || true
+
       - name: Generate Badge
         run: |
           rev=`git show-ref --head HEAD | cut -b 1-7`

scripts/check-doc.ts

@@ -0,0 +1,113 @@
+// This [Deno] program scans the compiled API documentation to check for errors.
+//
+// [Deno]: https://deno.land/
+//
+// Usage: deno run --allow-read scripts/check-workspace.ts
+import { parse as parseFlags } from "https://deno.land/std@0.125.0/flags/mod.ts";
+import { walk } from "https://deno.land/std@0.125.0/fs/mod.ts";
+import * as path from "https://deno.land/std@0.125.0/path/mod.ts";
+import * as log from "https://deno.land/std@0.125.0/log/mod.ts";
+
+const parsedArgs = parseFlags(Deno.args, {
+    "alias": {
+        h: "help",
+        d: "rustdoc-output",
+    },
+    "string": [
+        "rustdoc-output",
+    ],
+});
+
+if (parsedArgs["help"]) {
+    console.log("Arguments:");
+    console.log("  -h --help  Displays this message");
+    console.log("  -d DIRECTORY --rustdoc-output=DIRECTORY");
+    console.log("             Specifies the rustdoc output directory to scan. " +
+        "Defaults to `./target/doc` when unspecified.");
+}
+
+await log.setup({
+    handlers: {
+        console: new log.handlers.ConsoleHandler("DEBUG"),
+    },
+
+    loggers: {
+        default: {
+            level: "INFO",
+            handlers: ["console"],
+        },
+    },
+});
+
+const logger = log.getLogger();
+let hasError = false;
+let expectedRepository: string | null = null;
+
+// A code fragment indicating the presence of `common.md`
+const COMMON_CSS_FRAGMENT = /\.toc-header \+ ul::before {/g;
+// Code fragments that require the presence of `common.md`
+const COMMON_CSS_USES = [
+    /class="toc-header"/,
+    // The negative lookbehind is intended to avoid matching
+    // the example code in `common.md`
+    /(?<!\* *<div )class="admonition-follows"/,
+    /class="disabled-feature-warning"/,
+    // The negative lookbehind is intended to avoid matching
+    // the example code in `common.md`
+    /(?<!\* *<span )class="class"/,
+    '<cneter>',
+];
+
+await validateRustdocOutput(parsedArgs.d || "./target/doc");
+
+if (hasError) {
+    Deno.exit(1);
+}
+
+async function validateRustdocOutput(docPath: string): Promise<void> {
+    let numFilesScanned = 0;
+
+    logger.info(`Scanning ${docPath}`);
+    for await (const { path } of walk(docPath, { includeDirs: false })) {
+        if (!path.endsWith(".html") && !path.endsWith(".htm")) {
+            continue;
+        }
+
+        logger.debug(`# ${path}`);
+
+        const html = await Deno.readTextFile(path);
+        numFilesScanned += 1;
+
+        const numCommonCssInstances =
+            Array.from(html.matchAll(COMMON_CSS_FRAGMENT)).length;
+        if (numCommonCssInstances === 0) {
+            // Maybe a redirect page?
+            logger.debug(`${path}: Doesn't contain a fragment of 'common.md' - ignoring`);
+            continue;
+        } else if (numCommonCssInstances >= 2) {
+            // `#[doc = ...]` (per-file) + `$RUSTDOCFLAGS` [ref:doc_global_styling]
+            logger.debug(`${path}: There's a per-file inclusion of 'common.md' - ignoring`);
+
+            if (numCommonCssInstances > 2) {
+                logger.warning(`${path}: Includes too many instances of 'common.md'`);
+            }
+
+            continue;
+        } else {
+            // This file lacks a per-file incluson of `common.md`.
+        }
+
+        // To prevent the degradation of the appearance in the absence of the
+        // appropriate `$RUSTDOCFLAGS`, this page must be devoid of constructs
+        // that make use of the styling rules defined by `common.md`.
+        for (const cssUsage of COMMON_CSS_USES) {
+            if (html.match(cssUsage)) {
+                logger.error(`${path}: This file lacks a per-file inclusion of 'common.md', ` +
+                    `but includes a code fragment '${cssUsage}'`);
+                hasError = true;
+            }
+        }
+    }
+
+    logger.info(`${numFilesScanned} file(s) have been checked`);
+} // validateRustdocOutput

scripts/check-workspace.ts

@@ -10,6 +10,7 @@ import { parse as parseFlags } from "https://deno.land/std@0.125.0/flags/mod.ts"
 import { parse as parseToml } from "https://deno.land/std@0.125.0/encoding/toml.ts";
 import * as path from "https://deno.land/std@0.125.0/path/mod.ts";
 import * as log from "https://deno.land/std@0.125.0/log/mod.ts";
+import { exists } from "https://deno.land/std@0.125.0/fs/exists.ts";
 
 const parsedArgs = parseFlags(Deno.args, {
     "alias": {
@@ -42,10 +43,17 @@ await log.setup({
 });
 
 const EXPECTED_SOURCE_FRAGMENTS = [
-    // We want published crates to have consistent logos
-    '#![doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")]',
+    // We want published crates to have consistent logos, which should
+    // appear conditionally [ref:doc_feature]
+    `#![cfg_attr(
+    feature = "doc",
+    doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")
+)]`,
 ];
 
+const COMMON_HEADER_PATH = "src/common.md";
+const EXPECTED_RUSTDOC_ARGS = `--html-in-header ${COMMON_HEADER_PATH}`;
+
 const logger = log.getLogger();
 let hasError = false;
 let expectedRepository: string | null = null;
@@ -83,7 +91,7 @@ async function validateWorkspace(workspacePath: string): Promise<void> {
             continue;
         }
 
-        const {package: pkg, dependencies = {}} = crateMeta;
+        const {package: pkg, dependencies = {}, features = {}} = crateMeta;
         const {publish = true, version} = pkg;
 
         // CC-VER-UNPUBLISHED
@@ -146,6 +154,63 @@ async function validateWorkspace(workspacePath: string): Promise<void> {
                 }
             }
         }
+
+        // We want `common.md` applied for the entire crate in order that the
+        // upper-left custom logo is properly styled in official documentation
+        // builds [tag:doc_global_styling]
+        const docsMetadata = pkg?.metadata?.docs?.rs ?? {};
+        if (publish) {
+            const docsArgs = docsMetadata['rustdoc-args'] ?? [];
+
+            // Poor man's `docsArgs.windows(2).any(|x| x == ...)`
+            const docsArgsConcat = docsArgs.join(' ');
+            if (docsArgsConcat.indexOf(EXPECTED_RUSTDOC_ARGS) < 0) {
+                logger.error(`${crateRelPath}: package.metadata.docs.rs.rustdoc-args doesn't ` +
+                    `include '${EXPECTED_RUSTDOC_ARGS}'.`);
+                hasError = true;
+            }
+
+            // The file referenced by `EXPECTED_RUSTDOC_ARGS` should actually
+            // exist
+            const commonHeaderPath  = path.join(cratePath, COMMON_HEADER_PATH);
+            if (!await exists(commonHeaderPath)) {
+                logger.error(`${crateRelPath}: '${commonHeaderPath}' doesn't exist.`);
+                hasError = true;
+            }
+        }
+
+        // The custom logo needs a custom stylesheet [ref:doc_global_styling],
+        // so it must be disabled conditionally if the custom stylesheet isn't
+        // applied globally. The `doc` Cargo feature is used to toggle this.
+        // [tag:doc_feature] In summary, there are two cases we consider:
+        //
+        //  - In official documentation builds (docs.rs and our API
+        //    documentation website), the `doc` Cargo feature is enabled, and
+        //    the custom stylesheet is applied globally using `RUSTDOCFLAGS`.
+        //    The result is a custom logo styled consistently.
+        //
+        //  - In unofficial documentation builds (e.g., `cargo doc` in
+        //    downstream workspaces), the `doc` Cargo feature is disabled by
+        //    default, and the custom stylesheet is not applied globally. The
+        //    custom logo is disabled by `cfg_attr` in this case.
+        //
+        // We don't handle the cases where `doc` is enabled in unofficial
+        // builds. In such cases, the custom logo will be styled properly or
+        // improperly depending on whether `common.md` is included by `#[doc =
+        // ...]` in that file.
+        if (publish) {
+            if (typeof features.doc == "undefined") {
+                logger.error(`${crateRelPath}: features.doc is not present.`);
+                hasError = true;
+            }
+        }
+
+        // The enabled features must be consistent between docs.rs and
+        // our API documentation website [ref:doc_all_features]
+        if (publish && !docsMetadata["all-features"]) {
+            logger.error(`${crateRelPath}: package.metadata.docs.rs.all-features is ` +
+                `not set.`);
+        }
     }
 }
 
@@ -165,7 +230,16 @@ interface CargoMeta {
         keywords?: string[],
         repository?: string,
         publish?: boolean,
+        metadata?: {
+            docs?: {
+                rs?: {
+                    "rustdoc-args"?: string[],
+                    "all-features"?: boolean,
+                },
+            },
+        },
     },
+    features?: { [name: string]: string[] },
     dependencies?: { [name: string]: Dep },
     "dev-dependencies"?: { [name: string]: Dep },
 }

src/r3/Cargo.toml

@@ -17,7 +17,7 @@ sync = []
 # Exposes `r3_core`'s features'
 chrono_0p4 = ["r3_core/chrono_0p4"]
 
-# Enable the diagram rendering by svgbob and other fancy stuff
+# Enable the diagram rendering by svgbob and other fancy stuff [ref:doc_feature]
 doc = ["svgbobdoc/enable", "embed-doc-image", "r3_core/doc"]
 
 # Displays a "some features are disabled" warning in the documentation
@@ -39,3 +39,4 @@ r3_kernel = { path = "../r3_kernel" }
 [package.metadata.docs.rs]
 all-features = true
 targets = []
+rustdoc-args = ["--html-in-header", "src/common.md"]  # [ref:doc_global_styling]

src/r3/src/lib.rs

@@ -11,7 +11,10 @@
 #![feature(decl_macro)]
 #![feature(doc_cfg)]
 #![deny(unsafe_op_in_unsafe_fn)]
-#![doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")]
+#![cfg_attr(
+    feature = "doc",
+    doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")
+)]
 #![doc = include_str!("./lib.md")]
 #![doc = include_str!("./common.md")]
 // Work-around for [ref:rustdoc_images]

src/r3_core/Cargo.toml

@@ -11,7 +11,7 @@ repository = "https://github.com/r3-os/r3"
 [features]
 default = []
 
-# Enable the diagram rendering by svgbob and other fancy stuff
+# Enable the diagram rendering by svgbob and other fancy stuff [ref:doc_feature]
 doc = ["svgbobdoc/enable"]
 
 # Displays a "some features are disabled" warning in the documentation
@@ -41,3 +41,4 @@ log = "0.4.8"
 [package.metadata.docs.rs]
 all-features = true
 targets = []
+rustdoc-args = ["--html-in-header", "src/common.md"]  # [ref:doc_global_styling]

src/r3_core/src/lib.rs

@@ -51,7 +51,10 @@
 #![feature(doc_cfg)] // `#[doc(cfg(...))]`
 #![cfg_attr(test, feature(is_sorted))]
 #![deny(unsafe_op_in_unsafe_fn)]
-#![doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")]
+#![cfg_attr(
+    feature = "doc",
+    doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")
+)]
 #![doc = include_str!("./lib.md")]
 #![doc = include_str!("./common.md")]
 #![doc = include!("../doc/trait_binding.rs")] // `![trait_binding]`

src/r3_kernel/Cargo.toml

@@ -15,7 +15,7 @@ inline_syscall = []
 priority_boost = []
 system_time = []
 
-# Enable the diagram rendering by svgbob
+# Enable the diagram rendering by svgbob and other stuff [ref:doc_feature]
 doc = ["svgbobdoc/enable"]
 
 # Enable all optional kernel features
@@ -53,3 +53,4 @@ log = "0.4.8"
 [package.metadata.docs.rs]
 all-features = true
 targets = []
+rustdoc-args = ["--html-in-header", "src/common.md"]  # [ref:doc_global_styling]

src/r3_kernel/src/lib.rs

@@ -30,7 +30,10 @@
 #![feature(let_else)]
 #![feature(doc_cfg)] // `#[doc(cfg(...))]`
 #![deny(unsafe_op_in_unsafe_fn)]
-#![doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")]
+#![cfg_attr(
+    feature = "doc",
+    doc(html_logo_url = "https://r3-os.github.io/r3/logo-small.svg")
+)]
 #![doc = include_str!("./lib.md")]
 #![doc = include_str!("./common.md")]
 #![doc = include!("../doc/traits.rs")] // `![traits]`

src/r3_port_arm/Cargo.toml

@@ -11,6 +11,9 @@ repository = "https://github.com/r3-os/r3"
 [features]
 preload-registers = []
 
+# Used for documentation builds [ref:doc_feature]
+doc = []
+
 [dependencies]
 r3_portkit = { version = "0.1.0", path = "../r3_portkit" }
 r3_kernel = { version = "0.0.0", path = "../r3_kernel" }
@@ -21,4 +24,6 @@ memoffset = { version = "0.6.5", features = ["unstable_const"] }
 r0 = { version = "1.0.0" }
 
 [package.metadata.docs.rs]
+all-features = true
 targets = []
+rustdoc-args = ["--html-in-header", "src/common.md"]  # [ref:doc_global_styling]