Skip to content

Commit

Permalink
Fix Mermaid diagram rendering (#3875)
Browse files Browse the repository at this point in the history
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 <5588131+kianenigma@users.noreply.github.com>
Co-authored-by: Bastian Köcher <git@kchr.de>
  • Loading branch information
3 people authored Apr 4, 2024
1 parent 0bbda78 commit 0ef37c7
Show file tree
Hide file tree
Showing 7 changed files with 19 additions and 6 deletions.
5 changes: 2 additions & 3 deletions .gitlab/pipeline/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion cumulus/test/service/src/chain_spec.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
2 changes: 2 additions & 0 deletions docs/sdk/assets/after-content.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
<script> mermaid.init({ startOnLoad: true, theme: "dark" }, "pre.language-mermaid > code");</script>

2 changes: 2 additions & 0 deletions docs/sdk/headers/header.html → docs/sdk/assets/header.html
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
File renamed without changes.
11 changes: 11 additions & 0 deletions prdoc/pr_3875.prdoc
Original file line number Diff line number Diff line change
@@ -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: [ ]
3 changes: 1 addition & 2 deletions substrate/frame/assets/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 0ef37c7

Please sign in to comment.