Skip to content

Commit c8d1329

Browse files
CopilotSteake
Copilot
and
Steake
authored
Add comprehensive documentation portal with mdBook (#116)
* Initial plan * Add documentation portal with mdBook, API reference, and tutorials Co-authored-by: Steake <530040+Steake@users.noreply.github.com> * Add comprehensive documentation portal with 61 pages covering API, tutorials, and guides Co-authored-by: Steake <530040+Steake@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Steake <530040+Steake@users.noreply.github.com>
1 parent c5ab23b commit c8d1329

65 files changed

Lines changed: 3172 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy-docs.yml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [ master, main ]
6+
paths:
7+
- 'docs/book/**'
8+
- '.github/workflows/deploy-docs.yml'
9+
pull_request:
10+
branches: [ master, main ]
11+
paths:
12+
- 'docs/book/**'
13+
workflow_dispatch:
14+
15+
permissions:
16+
contents: read
17+
pages: write
18+
id-token: write
19+
20+
concurrency:
21+
group: "pages"
22+
cancel-in-progress: false
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Rust
32+
uses: actions-rust-lang/setup-rust-toolchain@v1
33+
with:
34+
toolchain: stable
35+
36+
- name: Install mdBook
37+
run: |
38+
cargo install mdbook --version 0.4.37 --locked
39+
40+
- name: Build Documentation
41+
run: |
42+
cd docs/book
43+
mdbook build
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v3
47+
with:
48+
path: docs/book/book
49+
50+
deploy:
51+
if: github.event_name != 'pull_request'
52+
needs: build
53+
runs-on: ubuntu-latest
54+
environment:
55+
name: github-pages
56+
url: ${{ steps.deployment.outputs.page_url }}
57+
steps:
58+
- name: Deploy to GitHub Pages
59+
id: deployment
60+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,8 @@ Cargo.lock
1616
*.profraw
1717
*.profdata
1818

19-
# Documentation
20-
docs/book/
19+
# Documentation (only ignore built output)
20+
docs/book/book/
2121

2222
# Temporary files
2323
/tmp/

‎docs/book/README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# BitCell Documentation
2+
3+
This directory contains the source for the BitCell documentation website, built with [mdBook](https://rust-lang.github.io/mdBook/).
4+
5+
## Building Locally
6+
7+
### Prerequisites
8+
9+
```bash
10+
cargo install mdbook --version 0.4.37
11+
```
12+
13+
### Build
14+
15+
```bash
16+
cd docs/book
17+
mdbook build
18+
```
19+
20+
Output will be in `docs/book/book/`.
21+
22+
### Development Server
23+
24+
```bash
25+
cd docs/book
26+
mdbook serve --open
27+
```
28+
29+
This will start a local server at `http://localhost:3000` with live reload.
30+
31+
## Structure
32+
33+
```
34+
docs/book/
35+
├── book.toml # mdBook configuration
36+
├── src/
37+
│ ├── SUMMARY.md # Table of contents
38+
│ ├── introduction.md
39+
│ ├── getting-started/
40+
│ ├── node/
41+
│ ├── wallet/
42+
│ ├── contracts/
43+
│ ├── api/
44+
│ ├── concepts/
45+
│ ├── advanced/
46+
│ ├── development/
47+
│ └── appendix/
48+
└── book/ # Built output (gitignored)
49+
```
50+
51+
## Contributing
52+
53+
To contribute to documentation:
54+
55+
1. Edit markdown files in `src/`
56+
2. Test locally with `mdbook serve`
57+
3. Submit a pull request
58+
59+
### Style Guide
60+
61+
- Use clear, concise language
62+
- Include code examples where appropriate
63+
- Add links to related sections
64+
- Test all commands/code samples
65+
- Use consistent formatting
66+
67+
## Deployment
68+
69+
Documentation is automatically built and deployed to GitHub Pages via `.github/workflows/deploy-docs.yml` when changes are pushed to master.
70+
71+
View live documentation at: https://docs.bitcell.network

‎docs/book/book.toml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
[book]
2+
authors = ["BitCell Core Team"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "BitCell Documentation"
7+
description = "Complete documentation for BitCell blockchain protocol - tournament consensus, zero-knowledge privacy, and smart contracts"
8+
9+
[build]
10+
build-dir = "book"
11+
create-missing = true
12+
13+
[preprocessor.links]
14+
15+
[output.html]
16+
default-theme = "rust"
17+
preferred-dark-theme = "navy"
18+
smart-punctuation = true
19+
git-repository-url = "https://github.com/Steake/BitCell"
20+
edit-url-template = "https://github.com/Steake/BitCell/edit/master/docs/book/{path}"
21+
site-url = "/BitCell/"
22+
cname = "docs.bitcell.network"
23+
24+
[output.html.print]
25+
enable = true
26+
27+
[output.html.fold]
28+
enable = true
29+
level = 1
30+
31+
[output.html.search]
32+
enable = true
33+
limit-results = 30
34+
teaser-word-count = 30
35+
use-boolean-and = true
36+
boost-title = 2
37+
boost-hierarchy = 1
38+
boost-paragraph = 1
39+
expand = true
40+
heading-split-level = 3
41+
42+
[output.html.playground]
43+
editable = false
44+
copyable = true
45+
line-numbers = true
46+
47+
[output.html.code]
48+
hidelines = { python = "~", rust = "#" }

‎docs/book/src/SUMMARY.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Summary
2+
3+
[Introduction](./introduction.md)
4+
5+
---
6+
7+
# Getting Started
8+
9+
- [Quick Start](./getting-started/quick-start.md)
10+
- [Installation](./getting-started/installation.md)
11+
- [Building from Source](./getting-started/building.md)
12+
- [Your First Transaction](./getting-started/first-transaction.md)
13+
14+
# Node Operation
15+
16+
- [Running a Node](./node/running-node.md)
17+
- [Validator Node Setup](./node/validator-setup.md)
18+
- [Miner Node Setup](./node/miner-setup.md)
19+
- [Network Configuration](./node/network-config.md)
20+
- [Node Troubleshooting](./node/troubleshooting.md)
21+
22+
# Wallet Guide
23+
24+
- [CLI Wallet](./wallet/cli-wallet.md)
25+
- [GUI Wallet](./wallet/gui-wallet.md)
26+
- [Creating Transactions](./wallet/transactions.md)
27+
- [Account Management](./wallet/account-management.md)
28+
- [Security Best Practices](./wallet/security.md)
29+
30+
# Smart Contracts
31+
32+
- [ZKVM Overview](./contracts/zkvm-overview.md)
33+
- [BCL Language Tutorial](./contracts/bcl-tutorial.md)
34+
- [ZKASM Assembly](./contracts/zkasm-reference.md)
35+
- [Contract Deployment](./contracts/deployment.md)
36+
- [Contract Testing](./contracts/testing.md)
37+
- [Gas & Optimization](./contracts/gas-optimization.md)
38+
- [Contract Examples](./contracts/examples.md)
39+
- [Token Contract](./contracts/examples/token.md)
40+
- [NFT Contract](./contracts/examples/nft.md)
41+
- [Escrow Contract](./contracts/examples/escrow.md)
42+
43+
# API Reference
44+
45+
- [Overview](./api/overview.md)
46+
- [JSON-RPC API](./api/json-rpc.md)
47+
- [Standard Methods (eth_*)](./api/json-rpc/eth-methods.md)
48+
- [BitCell Methods (bitcell_*)](./api/json-rpc/bitcell-methods.md)
49+
- [Transaction Methods](./api/json-rpc/transaction-methods.md)
50+
- [Block Methods](./api/json-rpc/block-methods.md)
51+
- [State Methods](./api/json-rpc/state-methods.md)
52+
- [WebSocket API](./api/websocket.md)
53+
- [Subscriptions](./api/websocket/subscriptions.md)
54+
- [Event Filtering](./api/websocket/filtering.md)
55+
- [REST API](./api/rest.md)
56+
- [Error Codes](./api/error-codes.md)
57+
58+
# Core Concepts
59+
60+
- [Tournament Consensus](./concepts/tournament-consensus.md)
61+
- [Cellular Automaton Battles](./concepts/ca-battles.md)
62+
- [Glider Patterns](./concepts/glider-patterns.md)
63+
- [EBSL Trust System](./concepts/ebsl-trust.md)
64+
- [Zero-Knowledge Proofs](./concepts/zk-proofs.md)
65+
- [Economics & Tokenomics](./concepts/economics.md)
66+
- [Ring Signatures & Privacy](./concepts/privacy.md)
67+
68+
# Advanced Topics
69+
70+
- [ZK Circuit Architecture](./advanced/zk-circuits.md)
71+
- [Protocol Specification](./advanced/protocol-spec.md)
72+
- [Network Architecture](./advanced/network-arch.md)
73+
- [State Management](./advanced/state-management.md)
74+
- [Cryptographic Primitives](./advanced/crypto-primitives.md)
75+
- [Performance Optimization](./advanced/performance.md)
76+
77+
# Development
78+
79+
- [Contributing Guide](./development/contributing.md)
80+
- [Development Setup](./development/dev-setup.md)
81+
- [Testing Guide](./development/testing.md)
82+
- [Code Style](./development/code-style.md)
83+
- [Architecture Overview](./development/architecture.md)
84+
85+
# Appendix
86+
87+
- [Glossary](./appendix/glossary.md)
88+
- [FAQ](./appendix/faq.md)
89+
- [Troubleshooting](./appendix/troubleshooting.md)
90+
- [Resources](./appendix/resources.md)
91+
- [Changelog](./appendix/changelog.md)

‎docs/book/src/advanced/crypto-primitives.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Cryptographic Primitives

‎docs/book/src/advanced/network-arch.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Network Architecture

‎docs/book/src/advanced/performance.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Performance Optimization

‎docs/book/src/advanced/protocol-spec.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Protocol Specification

‎docs/book/src/advanced/state-management.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# State Management

0 commit comments

Comments
 (0)