A holistic, minimal documentation portal for the Polkadot developers.

Overview

polkadot-sdk-docs

A holistic, minimal documentation portal for the Polkadot developers.

Master Tutorial

The very, very rough plan that I have so far is written in SCRIPT.md. Note that this topic is chosen such that it complements the imagine drawn in mini_substrate exercise in the PBA Rust entrance exam.

Tutorial Structure

This tutorial is being structured in branches. The main branch only contains staging folder that contains all of the written code. This is where the author of the tutorial prepares the next steps. Feel free to put whatever you need in there.

each tutorial step is places in a folder with the name step-{number}-more-info.

In this folder, we make to changes to staging, and instead only make changes to tutorial.

In order to develop a new step:

  • checkout to the corresponding steps branch.
  • merge main. This should always be conflict-free as it only brings the latest staging.
  • merge step-{n-1} to get the code of the previous step.
  • update content in tutorial based on the new step.
  • update README.md in tutorial to reflect the new step.

These README.md file can then be used to write:

  • a more structured written document
  • a slide deck
  • an interactive tutorial
  • ...

Existing steps:

In order to review each step, open the diff between step n and n-1 in github, and ignore anything in staging.

You might also like...
The Polkadot Hackathon Global Series North America edition is the second in a series of hackathons that brings the cutting edge of blockchain to a global community.

Polkadot Hackathon Project We are translating Uniswap v2 to Ink. Dependencies Install cargo-contract for building Ink contracts: cargo install dylint-

Firmware, application and documentation for the hackathon

eclipsecon-2022-hackathon WORK IN PROGRESS This repository contains software, firmware and documentation for the EclipseCon 2022 hackathon. Bluetooth

A guide for Mozilla's developers and data scientists to analyze and interpret the data gathered by our data collection systems.

Mozilla Data Documentation This documentation was written to help Mozillians analyze and interpret data collected by our products, such as Firefox and

The project brings the IC ecosystem to Unity, allowing Unity developers to call the functions of canisters on IC,
The project brings the IC ecosystem to Unity, allowing Unity developers to call the functions of canisters on IC,

Agent of Internet Computer for Unity The Intro The project brings the IC ecosystem to Unity, allowing Unity developers to call the functions of canist

Minimal implementation of the Mimblewimble protocol.

Grin Grin is an in-progress implementation of the Mimblewimble protocol. Many characteristics are still undefined but the following constitutes a firs

A Minimal Windows SDK.

Minimal Windows 10 SDK Installs only the necessary Windows 10 .lib files to save you having to download the full Visual Studio package. You can either

Minimal Substrate node configured for smart contracts via pallet-contracts.

substrate-contracts-node This repository contains Substrate's node-template configured to include Substrate's pallet-contracts ‒ a smart contract modu

Crib - Extensible, Minimal Template for Sway Projects

crib • Extensible, Minimal Template for Sway Projects. Developing First Time? New to rust? Install with: curl --proto '=https' --tlsv1.2 -sSf https://

Extensible, Minimal Template for Sway Projects

crib • Extensible, Minimal Template for Sway Projects. Developing First Time? New to rust? Install with: curl --proto '=https' --tlsv1.2 -sSf https://

Comments
  • Step 0 Master FRAME Tutorial Suggestions

    Step 0 Master FRAME Tutorial Suggestions

    I have made some suggestions that could become a presedicent for future tutorials. If the structure/content is agreeable, then I will gladly work on further diving into some of the concepts more in-depth and polishing this:

    Changes: There is an overall structure, a 'rustling' vibe. This would provide a guide to adding steps, and giving all necessary background info, and the outcome from this step:

    • Step 0 - Defining a pallet
      • Context: Project Setup and Background Knowledge
        • Project Setup
        • Background Knowledge: State Transitions
      • Tutorial Objectives
      • In the Code
      • Implementation

    Goals:

    • Relatively concise
    • Use more diagrams to show relationships between crucial parts of FRAME
    • Explain specific outcomes from this step, and ensure all steps connect to one another.
    • Reflect these changes in SCRIPT.md so anyone can replicate
    • We should use LOTS of links back to the Rust docs for various types and macros :) (didn't do here, but will do if this is a good way to go)

    Suggestions:

    • Is it possible to host this in a mdBook, that way t he progression is better highlighted and trackable?
    • What are the thoughts on heavily commented code, or should it be left blank whilst the README contains all the explaination?
    opened by CrackTheCode016 1
  • improve the experience when trying to find the substrate/polkadot CLI options via rust-docs.

    improve the experience when trying to find the substrate/polkadot CLI options via rust-docs.

    I think this is a great example of a page that should have been entirely documented in rust-docs: it is almost entirely copy-pasted, and extremely hard to maintain: https://docs.substrate.io/reference/command-line-tools/node-template/

    We should focus on the documentation of the crate https://paritytech.github.io/substrate/master/sc_cli/index.html and improve it such that this page can act as the single source of truth for CLI args.

    This crate should be linked in #11.

    generalist infra 
    opened by kianenigma 2
  • PoC for code-snippets-in-markdown system

    PoC for code-snippets-in-markdown system

    Recall:

    • Both the master tutorial's (#3) written code and reference docs (#4) will have code snippets.
    • None of these should to be hardcoded and all must come from valid sources that can be checked for validity, such as a git permalink.

    We need a system to build this, using Gatsby.

    Note that some more details might change as we flesh out how the master tutorial is being built. Perhaps, if we use diff files to denote each step of the tutorial, the snippets must come not from a permalink, but instead from a diff file.

    Moreover, we should also explore embedding pieces from docs.rs.

    infra 
    opened by kianenigma 9
  • Learn to customize the rust-docs page

    Learn to customize the rust-docs page

    So that we can hack it a bit to look more custom made.

    Also, there are a few hacks that if we find answers to, we can use:

    1. https://github.com/paritytech/substrate/issues/13818
    2. Make it show tests, examples, and so on
    3. Easier distinction between types that are storage and not.
    4. Easier distinction between enums and struct that are part of pallet macros and those that are not.
    5. Easier distinction between functions that are getters.
    6. Easier distinction between functions that are dispatchables.

    Some of these are being handled in an https://github.com/paritytech/substrate/tree/kiz-improve-fast-unstake-dcos, but in hacky ways.

    Some ideas from GPT-4:

    Rustdoc is a tool that generates documentation for Rust projects from doc-comments within the source code. While the default rendering is sufficient for most use-cases, you might want to customize it to better suit your needs or preferences. Here are a few hacks to tweak the rendering of Rustdocs:
    
    Custom CSS:
    You can add custom CSS to change the appearance of the generated documentation. Create a new CSS file, and include it in your Cargo.toml under the [package.metadata.docs.rs] section:
    
    toml
    Copy code
    [package.metadata.docs.rs]
    rustdoc-args = ["--html-in-header", "path/to/your/custom.css"]
    Now you can add any CSS rules to the custom file to modify the appearance of the Rustdoc output.
    
    Custom JavaScript:
    If you need more advanced control over the rendering, you can add custom JavaScript to the generated docs. Create a new JavaScript file and include it in your Cargo.toml as well:
    
    toml
    Copy code
    [package.metadata.docs.rs]
    rustdoc-args = ["--html-in-header", "path/to/your/custom.js"]
    With JavaScript, you can reorder sections, hide or show elements, or make other changes to the DOM as needed.
    
    Modify the theme:
    Rustdoc has a built-in theme switcher. You can create a custom theme by modifying the theme CSS files located in the src/librustdoc/html/static/themes directory in the Rustdoc source code. You can then include your custom theme in your project, allowing users to switch to it using the theme switcher.
    
    Custom HTML templates:
    Rustdoc uses Handlebars templates to generate the HTML output. You can create your own templates to customize the structure of the generated documentation. You'll need to modify the Rustdoc source code, located in the src/librustdoc/html directory, and then build a custom version of Rustdoc to use with your project.
    
    Fork Rustdoc:
    If you need extensive customization, you can fork the Rustdoc project, make your desired changes, and use your custom Rustdoc version to generate documentation for your projects. This approach allows you to have full control over the output and functionality but requires more effort to maintain and stay up-to-date with the official Rustdoc releases.
    
    Remember that making significant changes to the appearance or structure of Rustdocs can make it harder for other Rust users to navigate and understand your documentation. Be cautious with customizations and consider the impact on usability before implementing them.
    
    generalist infra 
    opened by kianenigma 4
Owner
Parity Technologies
Solutions for a trust-free world
Parity Technologies
Torii ⛩️ is a simple, powerful and extensible open-source Internal Developer Portal

Torii ⛩️ Torii is a simple, powerful and extensible open-source Internal Developer Portal where developers can find all the tools and services they ne

Qovery 64 Dec 17, 2023
Cross-chain hub for Crypto Asset on Polkadot

ChainX ChainX is a community-driven project built on the next-generation blockchain framework substrate, the largest Layer-2 network of Bitcoin using

ChainX 261 Dec 28, 2022
Polkadot Node Implementation

Polkadot Implementation of a https://polkadot.network node in Rust based on the Substrate framework. NOTE: In 2018, we split our implementation of "Po

Parity Technologies 6.5k Jan 6, 2023
The public source and documentation for Xenon iOS tweak.

THE GUIDE HAS BEEN MOVED TO THE WIKI This is the public source for the Xenon iOS tweak. The full version is available for $1.99 on Chariz. Differences

aspen 1 Dec 28, 2022
A node and runtime configuration for polkadot node.

MANTA NODE This repo is a fresh FRAME-based Substrate node, forked from substrate-developer-hub/substrate-node-templte ?? It links to pallet-manta-dap

Manta Network 14 Apr 25, 2021
🌍 The Earth Blockchain on Polkadot (archived)

Social Network Blockchain · The Social Network blockchain is a next-generation governance, economic, and social system for humanity built on Polkadot

social.network 18 Jan 2, 2023
Subsocial full node with Substrate/Polkadot pallets for decentralized communities: blogs, posts, comments, likes, reputation.

Subsocial Node by DappForce Subsocial is a set of Substrate pallets with web UI that allows anyone to launch their own decentralized censorship-resist

DappForce 74 Nov 24, 2022
A top-up of fatality based errors, originally developed for polkadot

fatality A generative approach to creating fatal and non-fatal errors. The generated source utilizes thiserror::Error derived attributes heavily, and

Bernhard Schuster 9 Sep 1, 2022
interBTC A trust-minimized bridge from Bitcoin to Polkadot.

interBTC A trust-minimized bridge from Bitcoin to Polkadot. Explore the specification » Report Bug · Request Feature This repository is hosted on GitH

Interlay 192 Dec 27, 2022
A re-write of polkadot staking miner using subxt to avoid hard dependency to each runtime version

Staking Miner v2 WARNING this library is under active development DO NOT USE IN PRODUCTION. The library is a re-write of polkadot staking miner using

Parity Technologies 19 Dec 28, 2022