initial docify readme with some content #6333 #7093

seemantaggarwal · 2025-01-08T17:00:10Z

Use docify export for parachain template hardcoded configuration and embed it in its README #6333

iulianbarbu

I haven't run this yet, but I think it needs a few tweaks before it runs successfully. LMK if anything is not clear.

iulianbarbu · 2025-01-10T09:50:53Z

templates/parachain/runtime/src/genesis_config_presets.rs

@@ -7,6 +7,13 @@ use alloc::{vec, vec::Vec};

 use polkadot_sdk::{staging_xcm as xcm, *};

+#[doc::include_str!("../../README.md")]
+#[cfg(feature = "generate-readme")]
+


nit: empty line can be removed.

iulianbarbu · 2025-01-10T09:51:14Z

templates/parachain/runtime/src/genesis_config_presets.rs

@@ -7,6 +7,13 @@ use alloc::{vec, vec::Vec};

 use polkadot_sdk::{staging_xcm as xcm, *};

+#[doc::include_str!("../../README.md")]


No need to include the README as a string here. This line can be removed.

iulianbarbu · 2025-01-10T09:55:33Z

templates/parachain/runtime/src/genesis_config_presets.rs


 /// Generate the session keys from individual elements.
 ///
 /// The input must be a tuple of individual keys (a single arg for now since we have just one key).
 pub fn template_session_keys(keys: AuraId) -> SessionKeys {
 	SessionKeys { aura: keys }
 }
+#[docify::export(name = "get_parachain_id")]


How about using export_content instead of export? This way we're getting only the PARACHAIN_ID var name.

iulianbarbu · 2025-01-10T09:56:06Z

templates/parachain/runtime/src/genesis_config_presets.rs

@@ -17,14 +24,19 @@ use sp_keyring::Sr25519Keyring;
 /// The default XCM version to set in genesis config.
 const SAFE_XCM_VERSION: u32 = xcm::prelude::XCM_VERSION;
 /// Parachain id used for genesis config presets of parachain template.
-pub const PARACHAIN_ID: u32 = 1000;
+#[export]
+pub const PARACHAIN_ID: u32 = 2000;


Looks like a leftover committed while testing Readme recompilation. We can change it back to 1000.

Oh, yeah, this is just mid level, a few commits will contain experimental values.

the final merge-able commit, I will revert

iulianbarbu · 2025-01-10T10:01:42Z

templates/parachain/README.docify.md

+cd parachain-template
+```
+
+## Starting a Development Chain


How about adding a note at the beginning of this section where we embed the PARACHAIN_ID const (as it is declared in the rust code), with docify::embed, as described in these docs (https://docs.rs/docify/latest/docify/macro.compile_markdown.html)?

This prepares the reader for these hardcoded values that will be used across the code base.

iulianbarbu · 2025-01-10T10:02:49Z

templates/parachain/runtime/src/genesis_config_presets.rs

+#[doc::include_str!("../../README.md")]
+#[cfg(feature = "generate-readme")]
+
+docify::compile_markdown!("../..","../..");


I think this should be:

Suggested change

docify::compile_markdown!("../..","../..");

docify::compile_markdown!("../../README.docify.md","../../README.md");

iulianbarbu · 2025-01-10T10:04:57Z

templates/parachain/runtime/src/genesis_config_presets.rs

+pub fn get_parachain_id() -> u32 {
+	PARACHAIN_ID
+}


Thinking again about this, I would have this function return a plain 1000 (such that it corresponds to the const PARACHAIN_ID). We should follow with a test that asserts PARACHAIN_ID == get_parachain_id(). Might sound redundant, but this is to overcome the lack of docify support around interpolating exported primitive constants by value directly into the README.

Then, we can directly use the get_parachain_id tag in the README.docify.md to interpolate 1000 into the doc wherever it is needed. I haven't tried this though, I have a slight concern it might not work everywhere.

Last thing would be to run cargo build --features generate-readme to trigger the README.md compilation, based on the README.docify.md file.

Suggested change

pub fn get_parachain_id() -> u32 {

PARACHAIN_ID

}

const fn get_parachain_id() -> u32 {

1000

}

iulianbarbu

Did a few changes to compile the README.md successfully. Please note that the patch has some backticks escaped (as in \```) to not break the diff block.

From 18b35fa42949cf33bd46fdc4c9dec487c0516d4e Mon Sep 17 00:00:00 2001
From: Iulian Barbu <iulian.barbu@parity.io>
Date: Mon, 13 Jan 2025 19:39:22 +0200
Subject: [PATCH 1/1] some fixes

Signed-off-by: Iulian Barbu <iulian.barbu@parity.io>
---
 Cargo.lock                           |  7 ++++
 Cargo.toml                           |  1 +
 templates/parachain/Cargo.toml       |  6 ++--
 templates/parachain/README.docify.md | 26 +++++++--------
 templates/parachain/README.md        | 48 ++++++++++++++++------------
 templates/parachain/src/lib.rs       | 35 ++++++++++++--------
 6 files changed, 74 insertions(+), 49 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 0a22179eb3d..fd191de1fc7 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -16134,6 +16134,13 @@ dependencies = [
  "staging-xcm-builder 17.0.1",
 ]
 
+[[package]]
+name = "parachain-template-docs"
+version = "0.0.0"
+dependencies = [
+ "docify",
+]
+
 [[package]]
 name = "parachain-template-node"
 version = "0.0.0"
diff --git a/Cargo.toml b/Cargo.toml
index c30a9949e85..48d7e7a8a71 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -538,6 +538,7 @@ members = [
 	"templates/minimal/node",
 	"templates/minimal/pallets/template",
 	"templates/minimal/runtime",
+	"templates/parachain",
 	"templates/parachain/node",
 	"templates/parachain/pallets/template",
 	"templates/parachain/runtime",
diff --git a/templates/parachain/Cargo.toml b/templates/parachain/Cargo.toml
index 5a495adacec..db3836631c2 100644
--- a/templates/parachain/Cargo.toml
+++ b/templates/parachain/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
-name = "parachain-template"
-description = "A parachain template built with Substrate, part of Polkadot Sdk."
+name = "parachain-template-docs"
+description = "A parachain-template helper crate to keep documentation in sync with the template's components."
 version = "0.0.0"
 license = "Unlicense"
 authors.workspace = true
@@ -11,6 +11,6 @@ publish = false
 
 [dependencies]
 docify = "0.2.8"
-parachain-template-runtime = { workspace = true, default-features = true }
+
 [features]
 generate-readme = []
diff --git a/templates/parachain/README.docify.md b/templates/parachain/README.docify.md
index 8c24e2acc0e..08975ffb958 100644
--- a/templates/parachain/README.docify.md
+++ b/templates/parachain/README.docify.md
@@ -1,9 +1,5 @@
 <div align="center">
 
-compile_markdown!("README.docify.md", "README.md");
-
-<!-- docify::embed!("src/lib.rs", embed_parachain_id)--> 
-
 # Polkadot SDK's Parachain Template
 
 <img height="70px" alt="Polkadot SDK Logo" src="https://github.com/paritytech/polkadot-sdk/raw/master/docs/images/Polkadot_Logo_Horizontal_Pink_White.png#gh-dark-mode-only"/>
@@ -25,11 +21,11 @@ compile_markdown!("README.docify.md", "README.md");
 
 - [Starting a Development Chain](#starting-a-development-chain)
 
-    - [Omni Node](#omni-node-prerequisites)
-    - [Zombienet setup with Omni Node](#zombienet-setup-with-omni-node)
-    - [Parachain Template Node](#parachain-template-node)
-    - [Connect with the Polkadot-JS Apps Front-End](#connect-with-the-polkadot-js-apps-front-end)
-    - [Takeaways](#takeaways)
+  - [Omni Node](#omni-node-prerequisites)
+  - [Zombienet setup with Omni Node](#zombienet-setup-with-omni-node)
+  - [Parachain Template Node](#parachain-template-node)
+  - [Connect with the Polkadot-JS Apps Front-End](#connect-with-the-polkadot-js-apps-front-end)
+  - [Takeaways](#takeaways)
 
 - [Runtime development](#runtime-development)
 - [Contributing](#contributing)
@@ -77,6 +73,12 @@ cd parachain-template
 
 ## Starting a Development Chain
 
+The parachain template relies on a hardcoded parachain id which is defined in the runtime code
+and referenced throughout the contents of this file as `{{PARACHAIN_ID}}`. Please replace
+any command or file referencing this placeholder with the value of the `PARACHAIN_ID` constant:
+
+<!-- docify::embed!("runtime/src/genesis_config_presets.rs", PARACHAIN_ID)-->
+
 ### Omni Node Prerequisites
 
 [Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html) can
@@ -100,7 +102,7 @@ Please see the installation section at [`crates.io/staging-chain-spec-builder`](
 #### Use `chain-spec-builder` to generate the `chain_spec.json` file
 
 \```sh
-chain-spec-builder create --relay-chain "rococo-local" --para-id <!-- docify::embed!("src/lib".rs", embed_parachain_id)--> --runtime \
+chain-spec-builder create --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
     target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development
 \```
 
@@ -145,7 +147,7 @@ export PATH="$PATH:<path/to/binaries>"
 \```toml
 # ...
 [[parachains]]
-id = <!-- docify::embed!("src/lib.rs", embed_parachain_id)-->
+id = {{PARACHAIN_ID}}
 chain_spec_path = "<TO BE UPDATED WITH A VALID PATH>"
 # ...
 \```
@@ -250,5 +252,3 @@ relay chain network (see [Parachain Template node](#parachain-template-node) set
 
 - 👥 Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and
   [Substrate StackExchange](https://substrate.stackexchange.com/).
-
-
diff --git a/templates/parachain/README.md b/templates/parachain/README.md
index c1e333df9e9..530ab3789fc 100644
--- a/templates/parachain/README.md
+++ b/templates/parachain/README.md
@@ -36,10 +36,10 @@
 - ⏫ This template provides a starting point to build a [parachain](https://wiki.polkadot.network/docs/learn-parachains).
 
 - ☁️ It is based on the
-[Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) framework.
+  [Cumulus](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/polkadot_sdk/cumulus/index.html) framework.
 
 - 🔧 Its runtime is configured with a single custom pallet as a starting point, and a handful of ready-made pallets
-such as a [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html).
+  such as a [Balances pallet](https://paritytech.github.io/polkadot-sdk/master/pallet_balances/index.html).
 
 - 👉 Learn more about parachains [here](https://wiki.polkadot.network/docs/learn-parachains)
 
@@ -50,18 +50,18 @@ A Polkadot SDK based project such as this one consists of:
 - 🧮 the [Runtime](./runtime/README.md) - the core logic of the parachain.
 - 🎨 the [Pallets](./pallets/README.md) - from which the runtime is constructed.
 - 💿 a [Node](./node/README.md) - the binary application, not part of the project default-members list and not compiled unless
-building the project with `--workspace` flag, which builds all workspace members, and is an alternative to
-[Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html).
+  building the project with `--workspace` flag, which builds all workspace members, and is an alternative to
+  [Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html).
 
 ## Getting Started
 
 - 🦀 The template is using the Rust language.
 
 - 👉 Check the
-[Rust installation instructions](https://www.rust-lang.org/tools/install) for your system.
+  [Rust installation instructions](https://www.rust-lang.org/tools/install) for your system.
 
 - 🛠️ Depending on your operating system and Rust version, there might be additional
-packages required to compile this template - please take note of the Rust compiler output.
+  packages required to compile this template - please take note of the Rust compiler output.
 
 Fetch parachain template code:
 
@@ -73,6 +73,14 @@ cd parachain-template
 
 ## Starting a Development Chain
 
+The parachain template development chain relies on a hardcoded parachain id which is defined in
+the runtime code and referenced throughout this README as `{{PARACHAIN_ID}}`. Please replace
+any command or file referencing this placeholder with the value of the `PARACHAIN_ID` constant:
+
+```rust,ignore
+pub const PARACHAIN_ID: u32 = 1000;
+```
+
 ### Omni Node Prerequisites
 
 [Omni Node](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/reference_docs/omni_node/index.html) can
@@ -96,12 +104,12 @@ Please see the installation section at [`crates.io/staging-chain-spec-builder`](
 #### Use `chain-spec-builder` to generate the `chain_spec.json` file
 
 \```sh
-chain-spec-builder create --relay-chain "rococo-local" --para-id 1000 --runtime \
+chain-spec-builder create --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
     target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development
 \```
 
 **Note**: the `relay-chain` and `para-id` flags are mandatory information required by
-Omni Node, and for parachain template case the value for `para-id` must be set to `1000`, since this
+Omni Node, and for parachain template case the value for `para-id` must be set to `{{PARACHAIN_ID}}`, since this
 is also the value injected through [ParachainInfo](https://docs.rs/staging-parachain-info/0.17.0/staging_parachain_info/)
 pallet into the `parachain-template-runtime`'s storage. The `relay-chain` value is set in accordance
 with the relay chain ID where this instantiation of parachain-template will connect to.
@@ -112,7 +120,7 @@ Start Omni Node with the generated chain spec. We'll start it in development mod
 and finalizing blocks based on manual seal, configured below to seal a block with each second.
 
 \```bash
-polkadot-omni-node --chain <path/to/chain_spec.json> --dev --dev-block-time 1000
+polkadot-omni-node --chain <path/to/chain_spec.json> --dev --dev-block-time 1000 
 \```
 
 However, such a setup is not close to what would run in production, and for that we need to setup a local
@@ -141,7 +149,7 @@ export PATH="$PATH:<path/to/binaries>"
 \```toml
 # ...
 [[parachains]]
-id = 1000
+id = {{PARACHAIN_ID}}
 chain_spec_path = "<TO BE UPDATED WITH A VALID PATH>"
 # ...
 \```
@@ -177,15 +185,15 @@ zombienet --provider native spawn zombienet.toml
 ### Connect with the Polkadot-JS Apps Front-End
 
 - 🌐 You can interact with your local node using the
-hosted version of the Polkadot/Substrate Portal:
-[relay chain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944)
-and [parachain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9988).
+  hosted version of the Polkadot/Substrate Portal:
+  [relay chain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9944)
+  and [parachain](https://polkadot.js.org/apps/#/explorer?rpc=ws://localhost:9988).
 
 - 🪐 A hosted version is also
-available on [IPFS](https://dotapps.io/).
+  available on [IPFS](https://dotapps.io/).
 
 - 🧑‍🔧 You can also find the source code and instructions for hosting your own instance in the
-[`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository.
+  [`polkadot-js/apps`](https://github.com/polkadot-js/apps) repository.
 
 ### Takeaways
 
@@ -211,7 +219,7 @@ Build the `parachain-template-runtime` as mentioned before in this guide and use
 again but this time by passing `--raw-storage` flag:
 
 \```sh
-chain-spec-builder create --raw-storage --relay-chain "rococo-local" --para-id 1000 --runtime \
+chain-spec-builder create --raw-storage --relay-chain "rococo-local" --para-id {{PARACHAIN_ID}} --runtime \
     target/release/wbuild/parachain-template-runtime/parachain_template_runtime.wasm named-preset development
 \```
 
@@ -234,15 +242,15 @@ relay chain network (see [Parachain Template node](#parachain-template-node) set
 - ➡️ Any pull requests should be directed to this [source](https://github.com/paritytech/polkadot-sdk/tree/master/templates/parachain).
 
 - 😇 Please refer to the monorepo's
-[contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and
-[Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CODE_OF_CONDUCT.md).
+  [contribution guidelines](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CONTRIBUTING.md) and
+  [Code of Conduct](https://github.com/paritytech/polkadot-sdk/blob/master/docs/contributor/CODE_OF_CONDUCT.md).
 
 ## Getting Help
 
 - 🧑‍🏫 To learn about Polkadot in general, [Polkadot.network](https://polkadot.network/) website is a good starting point.
 
 - 🧑‍🔧 For technical introduction, [here](https://github.com/paritytech/polkadot-sdk#-documentation) are
-the Polkadot SDK documentation resources.
+  the Polkadot SDK documentation resources.
 
 - 👥 Additionally, there are [GitHub issues](https://github.com/paritytech/polkadot-sdk/issues) and
-[Substrate StackExchange](https://substrate.stackexchange.com/).
+  [Substrate StackExchange](https://substrate.stackexchange.com/).
diff --git a/templates/parachain/src/lib.rs b/templates/parachain/src/lib.rs
index 3e3a43c197b..d3c5b8ba310 100644
--- a/templates/parachain/src/lib.rs
+++ b/templates/parachain/src/lib.rs
@@ -1,13 +1,22 @@
-pub mod runtime {
-    pub mod genesis_config_presets {
-        // Import the module as part of the crate's directory structure
-        include!("../runtime/src/genesis_config_presets.rs");
-    }
-}
-
-pub use runtime::genesis_config_presets::PARACHAIN_ID;
-
-#[docify::export_content]
-fn embed_parachain_id() -> String {
-    PARACHAIN_ID.to_string();
-}
+// Copyright (C) Parity Technologies (UK) Ltd.
+// This file is part of Cumulus.
+
+// Cumulus is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+
+// Cumulus is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+
+// You should have received a copy of the GNU General Public License
+// along with Cumulus.  If not, see <http://www.gnu.org/licenses/>.
+
+// The parachain-template crate helps with keeping the README.md in sync
+// with code sections across the components under the template: node,
+// pallets & runtime, by using `docify`.
+
+#[cfg(feature = "generate-readme")]
+docify::compile_markdown!("README.docify.md", "README.md");
-- 
2.43.0

paritytech-workflow-stopper · 2025-01-13T19:07:06Z

All GitHub workflows were cancelled due to failure one of the required jobs.
Failed workflow url: https://github.com/paritytech/polkadot-sdk/actions/runs/12754186826
Failed job name: fmt

seemantaggarwal added 7 commits January 8, 2025 22:28

initial docify readme with some content #6333

dd6429e

further improvement for docify, still buggy, mid level commit

5386289

reverting to one less experimental stage

75dbca0

keeping remote and local up to date

2e4f52b

further improvements in using docify

8cda7b3

removing function call for export call

45bce73

fixing docify imports

65f93a4

iulianbarbu reviewed Jan 10, 2025

View reviewed changes

seemantaggarwal added 3 commits January 11, 2025 23:42

addressing comments from iulian

318d589

further trials in docify

219baa4

mid level commit

757878d

iulianbarbu assigned seemantaggarwal Jan 13, 2025

seemantaggarwal added 2 commits January 13, 2025 16:10

fixing build errors

f7122d8

creating and toml and lib.rs for parachain directory

1e46e4f

iulianbarbu reviewed Jan 13, 2025

View reviewed changes

seemantaggarwal added 2 commits January 14, 2025 00:24

Patch from iulian barbu

96f915e

code cleanup

f7f73c0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

initial docify readme with some content #6333 #7093

initial docify readme with some content #6333 #7093

seemantaggarwal commented Jan 8, 2025

iulianbarbu left a comment

iulianbarbu Jan 10, 2025

iulianbarbu Jan 10, 2025

iulianbarbu Jan 10, 2025

iulianbarbu Jan 10, 2025

seemantaggarwal Jan 11, 2025

iulianbarbu Jan 10, 2025

iulianbarbu Jan 10, 2025

iulianbarbu Jan 10, 2025 •

edited

Loading

iulianbarbu left a comment •

edited

Loading

paritytech-workflow-stopper bot commented Jan 13, 2025

		@@ -7,6 +7,13 @@ use alloc::{vec, vec::Vec};

		use polkadot_sdk::{staging_xcm as xcm, *};

		#[doc::include_str!("../../README.md")]

	docify::compile_markdown!("../..","../..");
	docify::compile_markdown!("../../README.docify.md","../../README.md");

initial docify readme with some content #6333 #7093

Are you sure you want to change the base?

initial docify readme with some content #6333 #7093

Conversation

seemantaggarwal commented Jan 8, 2025

iulianbarbu left a comment

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

seemantaggarwal Jan 11, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025

Choose a reason for hiding this comment

iulianbarbu Jan 10, 2025 • edited Loading

Choose a reason for hiding this comment

iulianbarbu left a comment • edited Loading

Choose a reason for hiding this comment

paritytech-workflow-stopper bot commented Jan 13, 2025

iulianbarbu Jan 10, 2025 •

edited

Loading

iulianbarbu left a comment •

edited

Loading