docs: intial implementation based on rustdoc and mermaid (#966)

Co-authored-by: TaniaSaleem <[email protected]>
Co-authored-by: Metadata Update Bot <[email protected]>
Co-authored-by: penumbra23 <[email protected]>

.github/actions/rust-init/action.yaml

@@ -0,0 +1,14 @@
+name: "Init Rust"
+description: "Install Rust version with Timechain dependencies"
+
+inputs: {}
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install dependencies
+      shell: bash
+      run: sudo apt-get update && sudo apt-get install -y protobuf-compiler
+    - name: Install rust toolchain
+      shell: bash
+      run : rustup show

.github/workflows/build-docs.yaml

@@ -0,0 +1,30 @@
+name: Generate docs
+
+on:
+  pull_request:
+    paths-ignore:
+    - 'docker/**'
+    - 'infra/**'
+    - 'js/**'
+    - 'scripts/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout sources
+      uses: actions/checkout@v4
+    - name: Initialize Rust
+      uses: ./.github/actions/rust-init
+    - name: Build docs
+      run: cargo doc --no-deps --document-private-items --workspace
+    - name: Upload docs
+      uses: actions/upload-artifact@v4
+      with:
+        name: docs
+        if-no-files-found: error
+        path: target/doc

.github/workflows/build-runtime.yaml

@@ -92,6 +92,7 @@ jobs:
       uses: actions/checkout@v4
       with:
         ref: ${{ github.head_ref }}
+        submodules: recursive
     - name: Download and update Testnet Metadata
       id: download-testnet-default-metadata
       uses: actions/download-artifact@v4

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,33 @@
+name: Generate docs
+on:
+  push:
+    paths-ignore:
+      - 'docker/**'
+      - 'infra/**'
+      - 'js/**'
+      - 'scripts/**'
+    branches:
+      - 'development'
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Initialize Rust
+        uses: ./.github/actions/rust-init
+      - name: Build docs
+        run: cargo doc --no-deps --document-private-items --workspace
+      - name: Assemble structure
+        env:
+          DOCS_HIDEOUT: an8ohgahmoot6ro8ieReib9micau0Oow
+        run: |
+          cp -r target/doc target/docs/$DOCS_HIDEOUT
+          cp docs/robots.txt target/docs/$DOCS_HIDEOUT
+      - name: Deploy docs
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: target/docs

Cargo.toml

@@ -4,14 +4,14 @@ edition = "2021"
 version = "0.6.0"
 homepage = "https://analog.one/"
 license = "GPL-3.0-only"
-license-file = "LICENSE"
 readme = "README.md"
 repository = "https://github.com/Analog-Labs/timechain"
 
 [workspace]
 resolver = "2"
 members = [
 	"chronicle",
+	"docs",
 	"node",
 	"pallets/elections",
 	"pallets/members",
@@ -57,6 +57,8 @@ rosetta-client = { git = "https://github.com/analog-labs/chain-connectors" }
 rosetta-core = { git = "https://github.com/analog-labs/chain-connectors" }
 rosetta-config-ethereum = { git = "https://github.com/analog-labs/chain-connectors" }
 
+simple-mermaid = "0.1"
+
 [profile.release]
 # Runtime requires unwinding.
 panic = "unwind"

docs/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "analog-docs"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+timechain-node = { path = "../node" }
+
+timechain-runtime = { path = "../runtime" }
+
+pallet-elections = { path = "../pallets/elections" }
+pallet-members = { path = "../pallets/members" }
+pallet-networks = { path = "../pallets/networks" }
+pallet-shards = { path = "../pallets/shards" }
+pallet-tasks = { path = "../pallets/tasks" }
+pallet-timegraph = { path = "../pallets/timegraph" }
+
+chronicle = { path = "../chronicle" }

docs/robots.txt

@@ -0,0 +1,2 @@
+User-agent: *
+Disallow: /

docs/src/lib.rs

@@ -0,0 +1,27 @@
+//! # Analog Timechain Documentation
+//!
+//! This crate is a *minimal* but *always-accurate* documentation
+//! of the Timechain protocol.
+//!
+//! ## The Timechain Protocol
+//!
+//! The Analog Timechain is a substrate based solochain. It utilizes
+//! Babe and Grandpa to power its [`timechain_node`] and [`timechain_runtime`].
+//!
+//! On top of that it runs the Timechain protocol to attest and relay data
+//! between various chains. This protocol is executed by shards of [`chronicle`] nodes.
+//!
+//! ## Custom pallets
+//!
+//! - [`pallet_elections`]
+//! - [`pallet_members`]
+//! - [`pallet_networks`]
+//! - [`pallet_shards`]
+//! - [`pallet_tasks`]
+//! - [`pallet_timegraph`]
+//!
+#![warn(rustdoc::broken_intra_doc_links)]
+#![warn(rustdoc::private_intra_doc_links)]
+#![doc(html_favicon_url = "https://www.analog.one/images/favicon.ico")]
+#![doc(html_logo_url = "https://www.analog.one/images/logo.svg")]
+#![doc(issue_tracker_base_url = "https://github.com/Analog-Labs/timechain/issues")]

node/Cargo.toml

@@ -9,7 +9,6 @@ authors.workspace = true
 edition.workspace = true
 homepage.workspace = true
 license.workspace = true
-license-file.workspace = true
 repository.workspace = true
 readme.workspace = true
 

node/src/cli.rs

@@ -33,7 +33,7 @@ pub struct Cli {
 
 #[cfg(feature = "chronicle")]
 #[derive(Debug, clap::Parser)]
-/// workaround for https://github.com/clap-rs/clap/issues/5092
+/// workaround for <https://github.com/clap-rs/clap/issues/5092>
 #[group(requires_all = ["network_id", "target_url", "target_keyfile", "timechain_keyfile"], multiple = true)]
 pub struct ChronicleArgs {
 	/// The network to be used from Analog Connector.

pallets/members/Cargo.toml

@@ -28,6 +28,8 @@ sp-std = { git = "https://github.com/analog-labs/polkadot-sdk", tag = "v1.13.0-p
 
 time-primitives = { path = "../../primitives", default-features = false }
 
+simple-mermaid.workspace = true 
+
 [dev-dependencies]
 env_logger.workspace = true
 lazy_static = "1.4.0"