Skip to content

Commit 2c7227b

Browse files
cachebagcachebag
committed
docs: introduce mdbook
1 parent 89c3a03 commit 2c7227b

56 files changed

Lines changed: 2421 additions & 1 deletion

Some content is hidden

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

‎.github/workflows/docs.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/docs.yml'
10+
pull_request:
11+
paths:
12+
- 'docs/**'
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+
- uses: actions/checkout@v4
29+
30+
- name: Install mdBook
31+
run: |
32+
mkdir -p ~/bin
33+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.40/mdbook-v0.4.40-x86_64-unknown-linux-gnu.tar.gz | tar -xz -C ~/bin
34+
echo "$HOME/bin" >> $GITHUB_PATH
35+
36+
- name: Build book
37+
run: |
38+
cd docs
39+
mdbook build
40+
41+
- name: Upload artifact
42+
if: github.event_name != 'pull_request'
43+
uses: actions/upload-pages-artifact@v3
44+
with:
45+
path: docs/book
46+
47+
deploy:
48+
if: github.event_name != 'pull_request'
49+
needs: build
50+
runs-on: ubuntu-latest
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
[![Crates.io](https://img.shields.io/crates/v/nmrs)](https://crates.io/crates/nmrs)
44
[![Discord](https://img.shields.io/badge/chat-on%20discord-7289da?logo=discord&logoColor=white)](https://discord.gg/Sk3VfrHrN4)
55
[![Documentation](https://docs.rs/nmrs/badge.svg)](https://docs.rs/nmrs)
6+
[![User Guide](https://img.shields.io/badge/docs-mdBook-blue)](https://cachebag.github.io/nmrs/)
67
[![CI](https://github.com/cachebag/nmrs/actions/workflows/ci.yml/badge.svg)](https://github.com/cachebag/nmrs/actions/workflows/ci.yml)
78
[![License](https://img.shields.io/crates/l/nmrs)](LICENSE)
89

@@ -15,11 +16,17 @@ The project is divided into the following crates:
1516

1617
[Jump to the GUI section of this repo](#installation)
1718

19+
## Documentation
20+
21+
- **[User Guide](https://cachebag.github.io/nmrs/)** - Comprehensive guide with tutorials and examples
22+
- **[API Documentation](https://docs.rs/nmrs)** - Complete API reference on docs.rs
23+
- **[Discord](https://discord.gg/Sk3VfrHrN4)** - Join our community for help and discussion
24+
1825
## Getting Started
1926

2027
_Please consider joining the [**Discord**](https://discord.gg/Sk3VfrHrN4). It's a welcoming community to both developers who want to contribute and/or learn about and discuss nmrs as well as users that would like to be engaged with the development process._
2128

22-
The best way to get started with `nmrs` is the [API documentation](https://docs.rs/nmrs), which includes examples for common operations like scanning networks, connecting to Wi-Fi, and managing connection profiles.
29+
The best way to get started with `nmrs` is the [User Guide](https://cachebag.github.io/nmrs/), which includes comprehensive tutorials and examples. For detailed API information, see the [API documentation](https://docs.rs/nmrs).
2330

2431
## Sample usage
2532
We'll create a simple example that scans for available networks and connects to one. Note that these examples require NetworkManager to be running on your Linux system with D-Bus access, obviously.

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# mdBook output
2+
book/

‎docs/README.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# nmrs Documentation
2+
3+
This directory contains the mdBook-based user guide for nmrs.
4+
5+
## Building Locally
6+
7+
Install mdBook:
8+
9+
```bash
10+
cargo install mdbook
11+
```
12+
13+
Build the book:
14+
15+
```bash
16+
cd docs
17+
mdbook build
18+
```
19+
20+
Serve with live reload:
21+
22+
```bash
23+
mdbook serve --open
24+
```
25+
26+
The documentation will be available at http://localhost:3000
27+
28+
## Structure
29+
30+
- `src/` - Markdown source files
31+
- `book.toml` - mdBook configuration
32+
- `theme/` - Custom CSS and styling
33+
- `book/` - Generated output (gitignored)
34+
35+
## Contributing
36+
37+
When adding new pages:
38+
39+
1. Create the markdown file in the appropriate `src/` subdirectory
40+
2. Add it to `src/SUMMARY.md` to include it in the table of contents
41+
3. Build and preview locally to ensure it looks correct
42+
43+
## Deployment
44+
45+
The documentation is automatically built and deployed to GitHub Pages via the `.github/workflows/docs.yml` workflow on every push to `master`.

‎docs/add-page.sh‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
#!/bin/bash
2+
# Helper script to add new pages to the documentation
3+
4+
if [ $# -lt 2 ]; then
5+
echo "Usage: $0 <section> <page-name>"
6+
echo "Example: $0 guide wifi-configuration"
7+
echo ""
8+
echo "Available sections:"
9+
echo " - getting-started"
10+
echo " - guide"
11+
echo " - advanced"
12+
echo " - examples"
13+
echo " - gui"
14+
echo " - api"
15+
echo " - development"
16+
echo " - appendix"
17+
exit 1
18+
fi
19+
20+
SECTION=$1
21+
PAGE=$2
22+
TITLE=$(echo "${PAGE//-/ }" | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')
23+
24+
# Create the file
25+
cat > "src/${SECTION}/${PAGE}.md" << EOF
26+
# ${TITLE}
27+
28+
[Content to be added]
29+
30+
## Overview
31+
32+
...
33+
34+
## Examples
35+
36+
...
37+
38+
## See Also
39+
40+
- [Related page](../guide/other.md)
41+
EOF
42+
43+
echo "✓ Created src/${SECTION}/${PAGE}.md"
44+
echo ""
45+
echo "Next steps:"
46+
echo "1. Add content to src/${SECTION}/${PAGE}.md"
47+
echo "2. Add to src/SUMMARY.md in the appropriate section:"
48+
echo " - [${TITLE}](./${SECTION}/${PAGE}.md)"
49+
echo "3. Build and preview: mdbook serve"

‎docs/book.toml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
[book]
2+
title = "nmrs Documentation"
3+
description = "Comprehensive guide to using nmrs - A Rust API for NetworkManager"
4+
authors = ["Akrm Al-Hakimi"]
5+
language = "en"
6+
src = "src"
7+
8+
[rust]
9+
edition = "2021"
10+
11+
[build]
12+
build-dir = "book"
13+
create-missing = true
14+
use-default-preprocessors = true
15+
16+
[preprocessor.links]
17+
18+
[output.html]
19+
default-theme = "navy"
20+
preferred-dark-theme = "navy"
21+
git-repository-url = "https://github.com/cachebag/nmrs"
22+
edit-url-template = "https://github.com/cachebag/nmrs/edit/master/docs/{path}"
23+
site-url = "/nmrs/"
24+
cname = ""
25+
additional-css = ["theme/custom.css"]
26+
additional-js = []
27+
28+
[output.html.fold]
29+
enable = true
30+
level = 1
31+
32+
[output.html.playground]
33+
editable = true
34+
copyable = true
35+
copy-js = true
36+
line-numbers = true
37+
runnable = true
38+
39+
[output.html.search]
40+
enable = true
41+
limit-results = 30
42+
teaser-word-count = 30
43+
use-boolean-and = true
44+
boost-title = 2
45+
boost-hierarchy = 1
46+
boost-paragraph = 1
47+
expand = true
48+
heading-split-level = 3
49+
50+
[output.html.print]
51+
enable = true
52+
53+
[output.html.redirect]

‎docs/src/SUMMARY.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Summary
2+
3+
[Introduction](./introduction.md)
4+
5+
# Getting Started
6+
7+
- [Installation](./getting-started/installation.md)
8+
- [Quick Start](./getting-started/quick-start.md)
9+
- [Requirements](./getting-started/requirements.md)
10+
11+
# User Guide
12+
13+
- [WiFi Management](./guide/wifi.md)
14+
- [Scanning Networks](./guide/wifi-scanning.md)
15+
- [Connecting to Networks](./guide/wifi-connecting.md)
16+
- [WPA-PSK Networks](./guide/wifi-wpa-psk.md)
17+
- [WPA-EAP (Enterprise)](./guide/wifi-enterprise.md)
18+
- [Hidden Networks](./guide/wifi-hidden.md)
19+
- [VPN Connections](./guide/vpn.md)
20+
- [WireGuard Setup](./guide/vpn-wireguard.md)
21+
- [VPN Management](./guide/vpn-management.md)
22+
- [Ethernet Management](./guide/ethernet.md)
23+
- [Bluetooth](./guide/bluetooth.md)
24+
- [Device Management](./guide/devices.md)
25+
- [Connection Profiles](./guide/profiles.md)
26+
- [Real-Time Monitoring](./guide/monitoring.md)
27+
- [Error Handling](./guide/error-handling.md)
28+
29+
# Advanced Topics
30+
31+
- [Async Runtime Support](./advanced/async-runtimes.md)
32+
- [Custom Timeouts](./advanced/timeouts.md)
33+
- [Connection Options](./advanced/connection-options.md)
34+
- [D-Bus Architecture](./advanced/dbus.md)
35+
- [Logging and Debugging](./advanced/logging.md)
36+
37+
# Examples
38+
39+
- [Basic WiFi Scanner](./examples/wifi-scanner.md)
40+
- [WiFi Auto-Connect](./examples/wifi-auto-connect.md)
41+
- [Enterprise WiFi](./examples/enterprise-wifi.md)
42+
- [WireGuard VPN Client](./examples/wireguard-client.md)
43+
- [Network Monitor Dashboard](./examples/network-monitor.md)
44+
- [Connection Manager](./examples/connection-manager.md)
45+
46+
# nmrs-gui
47+
48+
- [GUI Overview](./gui/overview.md)
49+
- [Installation](./gui/installation.md)
50+
- [Configuration](./gui/configuration.md)
51+
- [Themes](./gui/themes.md)
52+
- [Waybar Integration](./gui/waybar.md)
53+
54+
# API Reference
55+
56+
- [Core Types](./api/types.md)
57+
- [NetworkManager](./api/network-manager.md)
58+
- [Models Module](./api/models.md)
59+
- [Builders Module](./api/builders.md)
60+
- [Error Types](./api/errors.md)
61+
62+
# Development
63+
64+
- [Contributing](./development/contributing.md)
65+
- [Architecture](./development/architecture.md)
66+
- [Testing](./development/testing.md)
67+
- [Release Process](./development/releases.md)
68+
69+
# Appendix
70+
71+
- [Troubleshooting](./appendix/troubleshooting.md)
72+
- [FAQ](./appendix/faq.md)
73+
- [Changelog](./appendix/changelog.md)
74+
- [License](./appendix/license.md)

‎docs/src/advanced/async-runtimes.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Async Runtimes
2+
3+
Documentation coming soon.

‎docs/src/advanced/connection-options.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Connection Options
2+
3+
Documentation coming soon.

‎docs/src/advanced/dbus.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Dbus
2+
3+
Documentation coming soon.

0 commit comments

Comments
 (0)