From 57221e45c0cf632d140c0a46377caa7d8a16776b Mon Sep 17 00:00:00 2001 From: Marcin S Date: Sun, 30 Oct 2022 15:18:05 +0100 Subject: [PATCH 1/4] Add a `last change` footer to the implementers guide Some of the newcomers were noticing outdated pages in the implementer's guide. This idea came up as a heuristic for how up-to-date an individual page is. --- roadmap/implementers-guide/README.md | 2 ++ roadmap/implementers-guide/book.toml | 6 ++++++ roadmap/implementers-guide/last-changed.css | 7 +++++++ 3 files changed, 15 insertions(+) create mode 100644 roadmap/implementers-guide/last-changed.css diff --git a/roadmap/implementers-guide/README.md b/roadmap/implementers-guide/README.md index 1775fb44d876..97066fb6f772 100644 --- a/roadmap/implementers-guide/README.md +++ b/roadmap/implementers-guide/README.md @@ -20,6 +20,8 @@ Then install and build the book: ```sh cargo install mdbook mdbook-linkcheck mdbook-graphviz mdbook-mermaid +# This plugin is not available on crates.io yet. +cargo install --git https://github.com/badboy/mdbook-last-changed/ --rev 2448157 mdbook serve roadmap/implementers-guide open http://localhost:3000 ``` diff --git a/roadmap/implementers-guide/book.toml b/roadmap/implementers-guide/book.toml index 8805ca4c38c3..0ced0e26f9a0 100644 --- a/roadmap/implementers-guide/book.toml +++ b/roadmap/implementers-guide/book.toml @@ -9,8 +9,14 @@ title = "The Polkadot Parachain Host Implementers' Guide" command = "mdbook-graphviz" [preprocessor.mermaid] command = "mdbook-mermaid" +[preprocessor.last-changed] +command = "mdbook-last-changed" +renderer = ["html"] [output.html] +additional-css = ["last-changed.css"] additional-js = ["mermaid.min.js", "mermaid-init.js"] +# Repository URL used in the last-changed link. +git-repository-url = "https://github.com/paritytech/polkadot" [output.linkcheck] diff --git a/roadmap/implementers-guide/last-changed.css b/roadmap/implementers-guide/last-changed.css new file mode 100644 index 000000000000..744dc6efc7ec --- /dev/null +++ b/roadmap/implementers-guide/last-changed.css @@ -0,0 +1,7 @@ +footer { + font-size: 0.8em; + text-align: center; + margin-top: 50px; + border-top: 1px solid black; + padding: 5px 0; +} From 3a08c05df5f02edfae2916c58f43ac98f770ca22 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Sun, 30 Oct 2022 15:40:30 +0100 Subject: [PATCH 2/4] Update `build-implementers-guide` CI job --- scripts/ci/gitlab/pipeline/build.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/ci/gitlab/pipeline/build.yml b/scripts/ci/gitlab/pipeline/build.yml index 791b01c2b632..fc423def17c1 100644 --- a/scripts/ci/gitlab/pipeline/build.yml +++ b/scripts/ci/gitlab/pipeline/build.yml @@ -171,6 +171,8 @@ build-implementers-guide: script: - apt-get -y update; apt-get install -y graphviz - cargo install mdbook mdbook-mermaid mdbook-linkcheck mdbook-graphviz + # This plugin is not available on crates.io yet. + - cargo install --git https://github.com/badboy/mdbook-last-changed/ --rev 2448157 - mdbook build ./roadmap/implementers-guide - mkdir -p artifacts - mv roadmap/implementers-guide/book artifacts/ From 81830ac2a6129276a63576421a4ce48c3e356e38 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Tue, 1 Nov 2022 22:32:56 +0100 Subject: [PATCH 3/4] Remove need to install mdbook-last-changed from github --- roadmap/implementers-guide/README.md | 4 +--- scripts/ci/gitlab/pipeline/build.yml | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/roadmap/implementers-guide/README.md b/roadmap/implementers-guide/README.md index 97066fb6f772..ae5f6f1e1a91 100644 --- a/roadmap/implementers-guide/README.md +++ b/roadmap/implementers-guide/README.md @@ -19,9 +19,7 @@ sudo apt-get install graphviz # for Ubuntu/Debian Then install and build the book: ```sh -cargo install mdbook mdbook-linkcheck mdbook-graphviz mdbook-mermaid -# This plugin is not available on crates.io yet. -cargo install --git https://github.com/badboy/mdbook-last-changed/ --rev 2448157 +cargo install mdbook mdbook-linkcheck mdbook-graphviz mdbook-mermaid mdbook-last-changed mdbook serve roadmap/implementers-guide open http://localhost:3000 ``` diff --git a/scripts/ci/gitlab/pipeline/build.yml b/scripts/ci/gitlab/pipeline/build.yml index fc423def17c1..c6fe5916c3b6 100644 --- a/scripts/ci/gitlab/pipeline/build.yml +++ b/scripts/ci/gitlab/pipeline/build.yml @@ -170,9 +170,7 @@ build-implementers-guide: - .collect-artifacts-short script: - apt-get -y update; apt-get install -y graphviz - - cargo install mdbook mdbook-mermaid mdbook-linkcheck mdbook-graphviz - # This plugin is not available on crates.io yet. - - cargo install --git https://github.com/badboy/mdbook-last-changed/ --rev 2448157 + - cargo install mdbook mdbook-mermaid mdbook-linkcheck mdbook-graphviz mdbook-last-changed - mdbook build ./roadmap/implementers-guide - mkdir -p artifacts - mv roadmap/implementers-guide/book artifacts/ From 4a20718a8472c70bcd7580119fffd96d8ee5f14a Mon Sep 17 00:00:00 2001 From: Marcin S Date: Tue, 1 Nov 2022 22:38:45 +0100 Subject: [PATCH 4/4] Fix minor typos and formatting issues --- roadmap/implementers-guide/README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/roadmap/implementers-guide/README.md b/roadmap/implementers-guide/README.md index ae5f6f1e1a91..7f3f8cef7e63 100644 --- a/roadmap/implementers-guide/README.md +++ b/roadmap/implementers-guide/README.md @@ -4,13 +4,14 @@ The implementers' guide is compiled from several source files with [`mdBook`](ht ## Hosted build -This is avalible at https://paritytech.github.io/polkadot/book/ +This is available [here](https://paritytech.github.io/polkadot/book/). ## Local build To view it locally from the repo root: Ensure graphviz is installed: + ```sh brew install graphviz # for macOS sudo apt-get install graphviz # for Ubuntu/Debian @@ -26,4 +27,4 @@ open http://localhost:3000 ## Specification -See also the Polkadot specificaton [hosted](https://spec.polkadot.network/), and it's [source](https://github.com/w3f/polkadot-spec)). +See also the Polkadot specification [hosted](https://spec.polkadot.network/), and its [source](https://github.com/w3f/polkadot-spec).