Skip to content

Commit 72f1f1f

Browse files
SurbhiAgarwal1SurbhiAgarwal1
committed
docs: introduce MkDocs configuration and deployment workflow (#1656)
Signed-off-by: SurbhiAgarwal1 <agarwalsurbhi1807@gmail.com>
1 parent 00657ff commit 72f1f1f

6 files changed

Lines changed: 291 additions & 1 deletion

File tree

‎.github/workflows/docs.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- 'mkdocs.yml'
10+
- 'requirements.txt'
11+
- '.github/workflows/docs.yml'
12+
pull_request:
13+
branches:
14+
- main
15+
paths:
16+
- 'docs/**'
17+
- 'mkdocs.yml'
18+
- 'requirements.txt'
19+
- '.github/workflows/docs.yml'
20+
21+
permissions:
22+
contents: write
23+
24+
jobs:
25+
deploy:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout code
29+
uses: actions/checkout@v4
30+
with:
31+
fetch-depth: 0
32+
33+
- name: Set up Python
34+
uses: actions/setup-python@v5
35+
with:
36+
python-version: '3.12'
37+
38+
- name: Cache dependencies
39+
uses: actions/cache@v4
40+
with:
41+
path: ~/.cache/pip
42+
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
43+
restore-keys: |
44+
${{ runner.os }}-pip-
45+
46+
- name: Install dependencies
47+
run: |
48+
python -m pip install --upgrade pip
49+
pip install -r requirements.txt
50+
51+
- name: Build documentation (Strict Mode)
52+
run: |
53+
mkdocs build --strict
54+
55+
- name: Deploy to GitHub Pages
56+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
57+
run: |
58+
mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ fabric-smart-client/
1111
cmd/token_validation_service/example-*.txt
1212
cmd/token_validation_service/out/
1313
/.antigravitycli/
14+
/site/

‎Makefile‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -242,4 +242,19 @@ update-all-deps-latest: ## Update all dependencies in all Go modules to their la
242242
@for dir in $$(find . -name "go.mod" -exec dirname {} \;); do \
243243
echo "=> Updating dependencies in $$dir"; \
244244
(cd $$dir && go get ./...@latest && go mod tidy); \
245-
done
245+
done
246+
247+
.PHONY: docs-install
248+
# Install documentation dependencies
249+
docs-install:
250+
pip install -r requirements.txt
251+
252+
.PHONY: docs-serve
253+
# Serve documentation locally for development
254+
docs-serve:
255+
mkdocs serve
256+
257+
.PHONY: docs-build
258+
# Build the static documentation site for production
259+
docs-build:
260+
mkdocs build --strict

‎docs/development/documentation.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Documentation Guide
2+
3+
This guide outlines how to contribute to, test, build, and deploy the static documentation site for the Fabric Token SDK.
4+
5+
Documentation is built using [MkDocs](https://www.mkdocs.org/) with the premium, responsive [Material for MkDocs theme](https://squidfunk.github.io/mkdocs-material/).
6+
7+
---
8+
9+
## 🛠️ Local Development Setup
10+
11+
To preview changes locally, you will need Python 3 installed on your system.
12+
13+
### 1. Install Dependencies
14+
Install the pinned documentation tools (including MkDocs and the Material theme) using the requirements file:
15+
16+
```bash
17+
make docs-install
18+
```
19+
20+
This target runs:
21+
```bash
22+
pip install -r requirements.txt
23+
```
24+
25+
### 2. Live Preview During Editing
26+
You can start a local development server that watches for file changes and automatically refreshes your browser:
27+
28+
```bash
29+
make docs-serve
30+
```
31+
32+
Once started, open your browser and navigate to:
33+
👉 **`http://127.0.0.1:8000`**
34+
35+
### 3. Build Static Site Locally
36+
To verify that all links are resolved and the site builds cleanly without any warnings:
37+
38+
```bash
39+
make docs-build
40+
```
41+
42+
This runs the strict compiler command:
43+
```bash
44+
mkdocs build --strict
45+
```
46+
47+
> [!IMPORTANT]
48+
> The `--strict` flag ensures that the build will fail if there are any warnings (such as orphaned files or broken internal links). Always verify your build with `make docs-build` before committing changes!
49+
50+
---
51+
52+
## 🚀 GitHub Pages Deployment Setup
53+
54+
The static documentation site is automatically built and deployed to GitHub Pages whenever changes are merged into the `main` branch.
55+
56+
If this is being set up on a new fork or repository for the first time, follow these steps to configure GitHub Pages:
57+
58+
1. **Navigate to Repository Settings**:
59+
Go to your repository page on GitHub, click on the **Settings** tab.
60+
2. **Access Pages Settings**:
61+
In the left sidebar under the "Code and automation" section, click on **Pages**.
62+
3. **Configure Build and Deployment**:
63+
- Under **Build and deployment** -> **Source**, select **"Deploy from a branch"**.
64+
- Under **Branch**, select `gh-pages` and set the folder to `/ (root)`.
65+
- Click **Save**.
66+
67+
The GitHub Actions workflow `.github/workflows/docs.yml` will automatically create and update the `gh-pages` branch on every merge.
68+
69+
---
70+
71+
## 📂 Documentation Directory Structure
72+
73+
All documentation source markdown files are located in the `docs/` directory of the project:
74+
75+
```
76+
docs/
77+
├── README.md # Home page
78+
├── configuration.md # Configuration guide
79+
├── development/ # Developer guidelines and guides
80+
│ ├── ai_agents.md # AI Agent context
81+
│ ├── documentation.md # This guide
82+
│ └── ... # Other development guidelines
83+
├── drivers/ # Fabric and ZK driver specs
84+
├── services/ # Core services (auditor, storage, ttx, etc.)
85+
└── imgs/ # Images and static assets
86+
```
87+
88+
### Adding New Documentation Pages
89+
1. Write your markdown file and place it in the appropriate subdirectory of `docs/`.
90+
2. Add your page to the navigation hierarchy in `mkdocs.yml` located at the root of the project.
91+
3. Validate your changes locally using `make docs-serve` or `make docs-build`.

‎mkdocs.yml‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
site_name: Fabric Token SDK
2+
site_url: https://hyperledger-labs.github.io/fabric-token-sdk/
3+
site_description: Privacy-preserving token management for Hyperledger Fabric
4+
site_author: Hyperledger Labs
5+
repo_url: https://github.com/hyperledger-labs/fabric-token-sdk
6+
repo_name: hyperledger-labs/fabric-token-sdk
7+
edit_uri: edit/main/docs/
8+
9+
validation:
10+
links:
11+
not_found: info
12+
anchors: info
13+
14+
theme:
15+
name: material
16+
palette:
17+
# Palette toggle for light mode
18+
- media: "(prefers-color-scheme: light)"
19+
scheme: default
20+
primary: indigo
21+
accent: indigo
22+
toggle:
23+
icon: material/brightness-7
24+
name: Switch to dark mode
25+
# Palette toggle for dark mode
26+
- media: "(prefers-color-scheme: dark)"
27+
scheme: slate
28+
primary: indigo
29+
accent: indigo
30+
toggle:
31+
icon: material/brightness-4
32+
name: Switch to light mode
33+
features:
34+
- navigation.tabs
35+
- navigation.sections
36+
- navigation.top
37+
- navigation.expand
38+
- navigation.tracking
39+
- search.suggest
40+
- search.highlight
41+
- content.code.copy
42+
- content.code.annotate
43+
44+
markdown_extensions:
45+
- admonition
46+
- pymdownx.details
47+
- pymdownx.superfences:
48+
custom_fences:
49+
- name: mermaid
50+
class: mermaid
51+
format: !!python/name:pymdownx.superfences.fence_code_format
52+
- pymdownx.highlight:
53+
anchor_linenums: true
54+
line_spans: __span
55+
pygments_lang_class: true
56+
- pymdownx.inlinehilite
57+
- pymdownx.snippets
58+
- pymdownx.tabbed:
59+
alternate_style: true
60+
- tables
61+
- toc:
62+
permalink: true
63+
64+
nav:
65+
- Home: README.md
66+
- Core Concepts:
67+
- Token SDK Overview: tokensdk.md
68+
- Token API: tokenapi.md
69+
- Token API Usage: token_sdk_usage.md
70+
- Driver API: driverapi.md
71+
- Configuration: configuration.md
72+
- Services Overview: services.md
73+
- Upgradability: upgradability.md
74+
- Public Parameters Lifecycle: public_parameters.md
75+
- Drivers:
76+
- Fabtoken: drivers/fabtoken.md
77+
- DLog (Zero-Knowledge): drivers/dlogwogh.md
78+
- Extending Validator: drivers/extending_validator.md
79+
- Metrics: drivers/metrics.md
80+
- Benchmark:
81+
- Overview: drivers/benchmark/benchmark.md
82+
- Tools: drivers/benchmark/tools.md
83+
- Core Drivers:
84+
- DLog No-GH Overview: drivers/benchmark/core/dlognogh/dlognogh.md
85+
- DLog No-GH Architecture: drivers/benchmark/core/dlognogh/dlognogh_architecture.md
86+
- DLog No-GH Regression: drivers/benchmark/core/dlognogh/dlognogh_regression.md
87+
- Benchmark Sender Results: drivers/benchmark/core/dlognogh/transfer_BenchmarkSender_results.md
88+
- Validator Transfer Profile: drivers/benchmark/core/dlognogh/validator_transfer_profile.md
89+
- Services:
90+
- Idemix Identity: drivers/benchmark/services/identity/idemix.md
91+
- Services:
92+
- Auditor: services/auditor.md
93+
- Benchmark: services/benchmark.md
94+
- Certifier: services/certifier.md
95+
- Config: services/config.md
96+
- Identity: services/identity.md
97+
- Interop: services/interop.md
98+
- Network Ethereum: services/network-ethereum.md
99+
- Network Fabric: services/network-fabric.md
100+
- Network Fabricx: services/network-fabricx.md
101+
- Network: services/network.md
102+
- NFT Tx: services/nfttx.md
103+
- Recovery: services/recovery.md
104+
- Selector: services/selector.md
105+
- Storage: services/storage.md
106+
- Tokens: services/tokens.md
107+
- TTX: services/ttx.md
108+
- Development:
109+
- Overview: development/development.md
110+
- General Guidelines: development/general.md
111+
- Idiomatic Go: development/idiomatic.md
112+
- Mocking: development/mock.md
113+
- Linting: development/linting.md
114+
- Makefile Guide: development/makefile.md
115+
- Monitoring: development/monitoring.md
116+
- Storage: development/storage.md
117+
- Testing: development/testing.md
118+
- Tokengen: development/tokengen.md
119+
- Tools: development/tools.md
120+
- Versioning: development/versioning.md
121+
- AI Agents: development/ai_agents.md
122+
- Documentation: development/documentation.md
123+
- Evolution: evolution_summary.md

‎requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
mkdocs==1.6.0
2+
mkdocs-material==9.5.39

0 commit comments

Comments
 (0)