From 0ef37c75401b78b61ed35ce27af8b964da27bb3c Mon Sep 17 00:00:00 2001
From: Liam Aharon <liam.aharon@hotmail.com>
Date: Thu, 4 Apr 2024 22:32:01 +1100
Subject: [PATCH] Fix Mermaid diagram rendering (#3875)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Closes https://github.com/paritytech/polkadot-sdk/issues/2977
The issue appears to stem from the `aquamarine` crate failing to render
diagrams in re-exported crates.
e.g. as raised
[here](https://github.com/paritytech/polkadot-sdk/issues/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
https://github.com/mersinvald/aquamarine/issues/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 <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Bastian Köcher <git@kchr.de>
---
.gitlab/pipeline/build.yml | 5 ++---
cumulus/test/service/src/chain_spec.rs | 2 +-
docs/sdk/assets/after-content.html | 2 ++
docs/sdk/{headers => assets}/header.html | 2 ++
docs/sdk/{headers => assets}/theme.css | 0
prdoc/pr_3875.prdoc | 11 +++++++++++
substrate/frame/assets/src/lib.rs | 3 +--
7 files changed, 19 insertions(+), 6 deletions(-)
create mode 100644 docs/sdk/assets/after-content.html
rename docs/sdk/{headers => assets}/header.html (97%)
rename docs/sdk/{headers => assets}/theme.css (100%)
create mode 100644 prdoc/pr_3875.prdoc
diff --git a/.gitlab/pipeline/build.yml b/.gitlab/pipeline/build.yml
index 3c870e576a8..8658e92efc8 100644
--- a/.gitlab/pipeline/build.yml
+++ b/.gitlab/pipeline/build.yml
@@ -91,7 +91,7 @@ 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
@@ -99,8 +99,7 @@ build-rustdoc:
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
index 61bbf755d89..e86023576ac 100644
--- 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
new file mode 100644
index 00000000000..30ae5c7ec43
--- /dev/null
+++ 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 b/docs/sdk/assets/header.html
similarity index 97%
rename from docs/sdk/headers/header.html
rename to docs/sdk/assets/header.html
index e28458c4ccc..f55c31b5321 100644
--- a/docs/sdk/headers/header.html
+++ b/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 b/docs/sdk/assets/theme.css
similarity index 100%
rename from docs/sdk/headers/theme.css
rename to docs/sdk/assets/theme.css
diff --git a/prdoc/pr_3875.prdoc b/prdoc/pr_3875.prdoc
new file mode 100644
index 00000000000..59cc3792d39
--- /dev/null
+++ 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
index e5fe2a3d1fd..6891f04dfb5 100644
--- 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
--
GitLab