Skip to content

Commit 884c997

Browse files
jensenboxjensenbox
committed
Add mdBook-based documentation for RustyHook
1 parent c56e6d2 commit 884c997

File tree

16 files changed

+1562
-2
lines changed

16 files changed

+1562
-2
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Build and Deploy Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'docs/**'
9+
- '.github/workflows/docs.yml'
10+
11+
jobs:
12+
deploy:
13+
runs-on: ubuntu-latest
14+
permissions:
15+
contents: write
16+
concurrency:
17+
group: ${{ github.workflow }}-${{ github.ref }}
18+
steps:
19+
- uses: actions/checkout@v3
20+
21+
- name: Setup mdBook
22+
uses: peaceiris/actions-mdbook@v1
23+
with:
24+
mdbook-version: 'latest'
25+
26+
- name: Build Documentation
27+
run: |
28+
cd docs/book
29+
mdbook build
30+
31+
- name: Deploy to GitHub Pages
32+
uses: peaceiris/actions-gh-pages@v3
33+
with:
34+
github_token: ${{ secrets.GITHUB_TOKEN }}
35+
publish_dir: ./docs/book/book
36+
publish_branch: gh-pages
37+
force_orphan: true
38+
cname: rustyhook.com # Optional: Set a custom domain

‎docs/book/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Generated book
2+
book/
3+
4+
# mdBook build artifacts
5+
.mdbook/

‎docs/book/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# RustyHook Documentation
2+
3+
This directory contains the source files for the RustyHook documentation website, built with [mdBook](https://rust-lang.github.io/mdBook/).
4+
5+
## Local Development
6+
7+
### Prerequisites
8+
9+
- [mdBook](https://rust-lang.github.io/mdBook/guide/installation.html) installed on your system
10+
11+
```sh
12+
cargo install mdbook
13+
```
14+
15+
### Building the Documentation
16+
17+
To build the documentation:
18+
19+
```sh
20+
cd docs/book
21+
mdbook build
22+
```
23+
24+
This will generate the HTML files in the `book` directory.
25+
26+
### Previewing the Documentation
27+
28+
To preview the documentation with live reloading:
29+
30+
```sh
31+
cd docs/book
32+
mdbook serve --open
33+
```
34+
35+
This will start a local web server and open the documentation in your default web browser. The documentation will automatically reload when you make changes to the source files.
36+
37+
## Documentation Structure
38+
39+
- `src/`: Contains the Markdown source files
40+
- `SUMMARY.md`: Defines the table of contents
41+
- `*.md`: Individual documentation pages
42+
- `book.toml`: Configuration file for mdBook
43+
- `theme/`: Custom styling and JavaScript (optional)
44+
45+
## Contributing to the Documentation
46+
47+
1. Make your changes to the Markdown files in the `src/` directory
48+
2. Preview your changes locally using `mdbook serve --open`
49+
3. Commit your changes and create a pull request
50+
51+
## Deployment
52+
53+
The documentation is automatically built and deployed to GitHub Pages when changes are pushed to the main branch. The GitHub Actions workflow is defined in `.github/workflows/docs.yml`.
54+
55+
## Additional Resources
56+
57+
- [mdBook Documentation](https://rust-lang.github.io/mdBook/)
58+
- [Markdown Guide](https://www.markdownguide.org/)

‎docs/book/book.toml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
[book]
2+
title = "RustyHook Documentation"
3+
authors = ["RustyHook Contributors"]
4+
description = "Documentation for RustyHook, a blazing-fast, Rust-native Git hook runner"
5+
src = "src"
6+
language = "en"
7+
8+
[output.html]
9+
git-repository-url = "https://github.com/your-org/rustyhook"
10+
edit-url-template = "https://github.com/your-org/rustyhook/edit/main/docs/book/{path}"
11+
site-url = "/rustyhook/"
12+
additional-css = ["theme/custom.css"]
13+
additional-js = ["theme/custom.js"]
14+
15+
[output.html.search]
16+
enable = true
17+
limit-results = 20
18+
teaser-word-count = 30
19+
use-boolean-and = true
20+
boost-title = 2
21+
boost-hierarchy = 1
22+
boost-paragraph = 1
23+
expand = true
24+
heading-split-level = 3

‎docs/book/src/SUMMARY.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Summary
2+
3+
[Introduction](index.md)
4+
5+
# User Guide
6+
- [Getting Started](user-guide/getting-started.md)
7+
- [Installation](user-guide/installation.md)
8+
- [CLI Usage](user-guide/cli-usage.md)
9+
- [Configuration](user-guide/configuration.md)
10+
- [Migration from pre-commit](user-guide/migration.md)
11+
- [Shell Completions](user-guide/shell-completions.md)
12+
13+
# Reference
14+
- [Supported Languages](reference/supported-languages.md)
15+
- [Hook Types](reference/hook-types.md)
16+
- [Configuration Reference](reference/configuration-reference.md)
17+
18+
# Advanced
19+
- [Monorepo Support](advanced/monorepo.md)
20+
- [Custom Hooks](advanced/custom-hooks.md)
21+
- [Performance Tuning](advanced/performance.md)
22+
23+
# Contributing
24+
- [Development Setup](contributing/development-setup.md)
25+
- [Architecture](contributing/architecture.md)
26+
- [Testing](contributing/testing.md)
27+
28+
[FAQ](faq.md)

‎docs/book/src/faq.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# Frequently Asked Questions
2+
3+
## General Questions
4+
5+
### What is RustyHook?
6+
7+
RustyHook is a blazing-fast, Rust-native Git hook runner designed to be a modern, drop-in replacement for `pre-commit`. It is language-agnostic, monorepo-friendly, and automatically provisions environments for linters and checkers written in Python, Node.js, Ruby, and more.
8+
9+
### How does RustyHook compare to pre-commit?
10+
11+
RustyHook is designed to be a faster, more efficient alternative to pre-commit with these key advantages:
12+
- Written in Rust for better performance
13+
- Concurrent hook execution
14+
- Native support for monorepos
15+
- Automatic environment setup for multiple languages
16+
- Compatible with existing pre-commit configurations
17+
18+
### Is RustyHook compatible with pre-commit configurations?
19+
20+
Yes! RustyHook can run your existing `.pre-commit-config.yaml` files using the `rh compat` command. You can also convert your pre-commit configuration to RustyHook's native format using `rh convert`.
21+
22+
## Installation and Setup
23+
24+
### How do I install RustyHook?
25+
26+
The easiest way to install RustyHook is using Cargo:
27+
28+
```sh
29+
cargo install rustyhook
30+
```
31+
32+
For other installation methods, see the [Installation Guide](user-guide/installation.md).
33+
34+
### How do I set up RustyHook in my project?
35+
36+
To set up RustyHook in your project:
37+
38+
1. Install RustyHook
39+
2. Initialize a configuration file:
40+
```sh
41+
rh init
42+
```
43+
3. Edit the `.rustyhook/config.yaml` file to configure your hooks
44+
4. Install the Git hooks:
45+
```sh
46+
rh install
47+
```
48+
49+
### Can I use RustyHook with CI/CD systems?
50+
51+
Yes, RustyHook works well in CI/CD environments. You can run hooks using:
52+
53+
```sh
54+
rh run --all-files
55+
```
56+
57+
This will run all hooks on all files, not just changed ones.
58+
59+
## Configuration
60+
61+
### How do I configure RustyHook?
62+
63+
RustyHook uses a YAML configuration file located at `.rustyhook/config.yaml`. See the [Configuration Guide](user-guide/configuration.md) for details.
64+
65+
### Can I use RustyHook in a monorepo?
66+
67+
Yes, RustyHook is designed with monorepos in mind. You can have multiple configuration files in different directories, and RustyHook will use the closest configuration file to the Git root.
68+
69+
### How do I add a new hook?
70+
71+
To add a new hook, edit your `.rustyhook/config.yaml` file and add a new entry to the `hooks` array:
72+
73+
```yaml
74+
hooks:
75+
- id: my-new-hook
76+
language: python
77+
version: "==1.0.0"
78+
entry: "my-hook-command"
79+
files: "\\.py$"
80+
```
81+
82+
## Troubleshooting
83+
84+
### My hooks aren't running. What should I check?
85+
86+
1. Make sure RustyHook is installed correctly (`rh --version`)
87+
2. Check that your configuration file is valid (`rh doctor`)
88+
3. Verify that Git hooks are installed (`ls -la .git/hooks`)
89+
4. Run hooks manually to see any errors (`rh run --verbose`)
90+
91+
### How do I debug hook failures?
92+
93+
Use the `--verbose` flag to get more detailed output:
94+
95+
```sh
96+
rh run --verbose
97+
```
98+
99+
You can also use the `doctor` command to diagnose issues:
100+
101+
```sh
102+
rh doctor
103+
```
104+
105+
### How do I clean up cached environments?
106+
107+
To clean up cached environments:
108+
109+
```sh
110+
rh clean --all
111+
```
112+
113+
Or to clean only specific language environments:
114+
115+
```sh
116+
rh clean --language python
117+
```
118+
119+
## Advanced Usage
120+
121+
### Can I run hooks on specific files?
122+
123+
Yes, you can run hooks on specific files:
124+
125+
```sh
126+
rh run --files src/main.rs,src/lib.rs
127+
```
128+
129+
### How do I skip hooks for a specific commit?
130+
131+
To skip hooks for a specific commit:
132+
133+
```sh
134+
git commit --no-verify
135+
```
136+
137+
Or with the `-n` shorthand:
138+
139+
```sh
140+
git commit -n
141+
```
142+
143+
### Can I use RustyHook with hooks other than pre-commit?
144+
145+
Yes, RustyHook supports various Git hooks:
146+
147+
```sh
148+
rh install --hook-type pre-push
149+
```
150+
151+
## Contributing
152+
153+
### How can I contribute to RustyHook?
154+
155+
We welcome contributions! See the [Contributing Guide](contributing/development-setup.md) for details on how to get started.
156+
157+
### Where can I report bugs or request features?
158+
159+
You can report bugs or request features on the [GitHub issue tracker](https://github.com/your-org/rustyhook/issues).

‎docs/book/src/index.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# RustyHook
2+
3+
**RustyHook** is a blazing-fast, Rust-native Git hook runner designed to be a modern, drop-in replacement for [`pre-commit`](https://pre-commit.com/). It is language-agnostic, monorepo-friendly, and automatically provisions environments for linters and checkers written in Python, Node.js, Ruby, and more.
4+
5+
## Features
6+
7+
* 🚀 **Fast and concurrent** execution powered by Rust
8+
* 🧰 **Automatic setup** of Python virtualenvs, Node/npm environments, and Ruby/bundler installs
9+
* 🌐 **Language-agnostic** support with consistent hook interface
10+
* 🏗️ **Monorepo-first** with per-directory or per-project configurations
11+
* 🪝 **Compatibility with `.pre-commit-config.yaml`**
12+
* 🧙 **Migration tool** to convert pre-commit configs to native `.rustyhook/config.yaml`
13+
* 📦 **Cache-aware** tool installs and version pinning
14+
* 🆔 CLI alias: `rh`
15+
16+
## Quick Start
17+
18+
```sh
19+
# Install RustyHook
20+
cargo install rustyhook
21+
22+
# Initialize a new configuration
23+
rh init
24+
25+
# Run your hooks
26+
rh run
27+
```
28+
29+
For more detailed information, check out the [Getting Started](user-guide/getting-started.md) guide.
30+
31+
## Documentation Sections
32+
33+
- **[User Guide](user-guide/getting-started.md)**: Learn how to install, configure, and use RustyHook
34+
- **[Reference](reference/supported-languages.md)**: Detailed reference for supported languages, hook types, and configuration options
35+
- **[Advanced](advanced/monorepo.md)**: Advanced topics like monorepo support, custom hooks, and performance tuning
36+
- **[Contributing](contributing/development-setup.md)**: Information for developers who want to contribute to RustyHook
37+
38+
## License
39+
40+
RustyHook is licensed under the MIT License.
41+
42+
## Acknowledgments
43+
44+
* Inspired by `pre-commit`, `lefthook`, `moonrepo`, and the Rust community
45+
* Shoutout to contributors and early testers helping shape this project

0 commit comments

Comments
 (0)