Fix Mermaid diagram rendering (#3875)

Closes #2977 The issue appears to stem from the `aquamarine` crate failing to render diagrams in re-exported crates. e.g. as raised [here](#2977), diagrams would render at `frame_support::traits::Hooks` but not the re-exported doc `frame::traits::Hooks`, even if I added `aquamarine` as a `frame` crate dependency. To resolve this, I followed advice in mersinvald/aquamarine#20 to instead render mermaid diagrams directly using JS by adding an `after-content.js`. --- Also fixes compile warnings, enables `--all-features` and disallows future warnings in CI. --------- Co-authored-by: Kian Paimani <[email protected]> Co-authored-by: Bastian Köcher <[email protected]>
paritytech · Apr 9, 2024 · 63064e6 · 63064e6
1 parent 73fdff8
commit 63064e6
Show file tree

Hide file tree

Showing 7 changed files with 19 additions and 6 deletions.
diff --git a/.gitlab/pipeline/build.yml b/.gitlab/pipeline/build.yml
@@ -91,16 +91,15 @@ build-rustdoc:
     - .run-immediately
   variables:
     SKIP_WASM_BUILD: 1
-    RUSTDOCFLAGS: "--default-theme=ayu --html-in-header ./docs/sdk/headers/header.html --extend-css ./docs/sdk/headers/theme.css"
+    RUSTDOCFLAGS: "-Dwarnings --default-theme=ayu --html-in-header ./docs/sdk/assets/header.html --extend-css ./docs/sdk/assets/theme.css --html-after-content ./docs/sdk/assets/after-content.html"
   artifacts:
     name: "${CI_JOB_NAME}_${CI_COMMIT_REF_NAME}-doc"
     when: on_success
     expire_in: 1 days
     paths:
       - ./crate-docs/
   script:
-    # FIXME: it fails with `RUSTDOCFLAGS="-Dwarnings"` and `--all-features`
-    - time cargo doc --features try-runtime,experimental --workspace --no-deps
+    - time cargo doc --all-features --workspace --no-deps
     - rm -f ./target/doc/.lock
     - mv ./target/doc ./crate-docs
     # Inject Simple Analytics (https://www.simpleanalytics.com/) privacy preserving tracker into

diff --git a/cumulus/test/service/src/chain_spec.rs b/cumulus/test/service/src/chain_spec.rs
@@ -34,7 +34,7 @@ pub fn get_from_seed<TPublic: Public>(seed: &str) -> <TPublic::Pair as Pair>::Pu
 		.public()
 }
 
-/// The extensions for the [`ChainSpec`](crate::ChainSpec).
+/// The extensions for the [`ChainSpec`].
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ChainSpecGroup, ChainSpecExtension)]
 #[serde(deny_unknown_fields)]
 pub struct Extensions {

diff --git a/docs/sdk/assets/after-content.html b/docs/sdk/assets/after-content.html
@@ -0,0 +1,2 @@
+<script> mermaid.init({ startOnLoad: true, theme: "dark" }, "pre.language-mermaid > code");</script>
+
diff --git a/docs/sdk/headers/header.html → docs/sdk/assets/header.html b/docs/sdk/headers/header.html → docs/sdk/assets/header.html
@@ -84,6 +84,8 @@
 	});
 </script>
 
+<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+
 <style>
 	body.sdk-docs {
 		nav.side-bar {

diff --git a/docs/sdk/headers/theme.css → docs/sdk/assets/theme.css b/docs/sdk/headers/theme.css → docs/sdk/assets/theme.css
diff --git a/prdoc/pr_3875.prdoc b/prdoc/pr_3875.prdoc
@@ -0,0 +1,11 @@
+# Schema: Polkadot SDK PRDoc Schema (prdoc) v1.0.0
+# See doc at https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/prdoc/schema_user.json
+
+title: Fix Mermaid diagram rendering
+
+doc:
+  - audience: Runtime Dev
+    description: |
+      Fixes the rendering of some Mermaid diagrams in the documentation.
+
+crates: [ ]
diff --git a/substrate/frame/assets/src/lib.rs b/substrate/frame/assets/src/lib.rs
@@ -18,8 +18,7 @@
 //! # Assets Pallet
 //!
 //! A simple, secure module for dealing with sets of assets implementing
-//! [`fungible`](frame_support::traits::fungible) traits, via
-//! [`fungibles`](frame_support::traits::fungibles) traits.
+//! [`fungible`](frame_support::traits::fungible) traits, via [`fungibles`] traits.
 //!
 //! The pallet makes heavy use of concepts such as Holds and Freezes from the
 //! [`frame_support::traits::fungible`] traits, therefore you should read and understand those docs