Skip to content

Commit f530d43

Browse files
VeykrilVeykril
committed
Generate the manual mdbook
1 parent 4ac29c2 commit f530d43

File tree

18 files changed

+5383
-0
lines changed

18 files changed

+5383
-0
lines changed

‎manual/.gitignore

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

‎manual/Makefile

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
.PHONY: deploy
2+
deploy: book
3+
@echo "====> deploying to github"
4+
git worktree add /tmp/book gh-pages
5+
mdbook build
6+
rm -rf /tmp/book/*
7+
cp -rp book/* /tmp/book/
8+
cd /tmp/book && \
9+
git add -A && \
10+
git commit -m "deployed on $(shell date) by ${USER}" && \
11+
git push origin gh-pages

‎manual/README.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# rust-analyzer documentation
2+
3+
The rust analyzer manual uses [mdbook](https://rust-lang.github.io/mdBook/).
4+
5+
## Quick start
6+
7+
To run the documentation site locally:
8+
9+
```shell
10+
cargo install mdbook
11+
cd docs/book
12+
mdbook serve
13+
# make changes to documentation files in doc/book/src
14+
# ...
15+
```
16+
17+
mdbook will rebuild the documentation as changes are made.
18+
19+
## Making updates
20+
21+
While not required, installing the mdbook binary can be helfpul in order to see the changes.
22+
Start with the mdbook [User Guide](https://rust-lang.github.io/mdBook/guide/installation.html) to familiarize yourself with the tool.
23+
24+
## Generated documentation
25+
26+
Four sections are generated dynamically: assists, configuration, diagnostics and features. Their content is found in the `generated.md` files
27+
of the respective book section, for example `src/configuration/generated.md`, and are included in the book via mdbook's
28+
[include](https://rust-lang.github.io/mdBook/format/mdbook.html#including-files) functionality. Generated files can be rebuilt by running the various
29+
test cases that generate them, or by simply running all of the `rust-analyzer` tests with `cargo test`.

‎manual/book.toml

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
[book]
2+
authors = ["The rust-analyzer authors"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "rust-analyzer"
7+
8+
[rust]
9+
edition = "2021"
10+
11+
[output.html]
12+
edit-url-template = "https://github.com/rust-lang/rust-analyzer/edit/master/manual/{path}"
13+
git-repository-url = "https://github.com/rust-lang/rust-analyzer/tree/master/manual"
14+
mathjax-support = true
15+
site-url = "/rust-analyzer/"
16+
17+
[output.html.playground]
18+
editable = true
19+
runnable = false
20+
line-numbers = true
21+
22+
[output.html.search]
23+
boost-hierarchy = 2
24+
boost-paragraph = 1
25+
boost-title = 2
26+
expand = true
27+
heading-split-level = 2
28+
limit-results = 20
29+
use-boolean-and = true
30+
31+
[output.html.redirect]
32+
"/manual.html" = "/index.html"
33+
34+
[output.html.fold]
35+
enable = true
36+
level = 3
37+
38+
[preprocessor.toc]
39+
command = "mdbook-toc"
40+
renderer = ["html"]
41+
max-level = 3

‎manual/src/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# rust-analyzer
2+
3+
At its core, rust-analyzer is a **library** for semantic analysis of
4+
Rust code as it changes over time. This manual focuses on a specific
5+
usage of the library — running it as part of a server that implements
6+
the [Language Server
7+
Protocol](https://microsoft.github.io/language-server-protocol/) (LSP).
8+
The LSP allows various code editors, like VS Code, Emacs or Vim, to
9+
implement semantic features like completion or goto definition by
10+
talking to an external language server process.
11+
12+
To improve this document, send a pull request:
13+
[https://github.com/rust-lang/rust-analyzer](https://github.com/rust-lang/rust-analyzer/blob/docs/book/README.md)
14+
15+
The manual is written in markdown and includes
16+
some extra files which are generated from the source code. Run
17+
`cargo test` and `cargo test -p xtask` to create these.
18+
19+
If you have questions about using rust-analyzer, please ask them in the
20+
[“IDEs and Editors”](https://users.rust-lang.org/c/ide/14) topic of Rust
21+
users forum.

‎manual/src/SUMMARY.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Summary
2+
3+
- [Introduction](README.md)
4+
- [Installation](installation/README.md)
5+
- [Troubleshooting](troubleshooting/README.md)
6+
- [Configuration](configuration/README.md)
7+
- [Non-Cargo Based Projects](non_cargo_based_projects/README.md)
8+
- [Security](security/README.md)
9+
- [Privacy](privacy/README.md)
10+
- [Features](features/README.md)
11+
- [Assists (Code Actions)](assists/README.md)
12+
- [Diagnostics](diagnostics/README.md)
13+
- [Editor Features](editor_features/README.md)

‎manual/src/assists/README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Assists
2+
3+
Assists, or code actions, are small local refactorings, available in a
4+
particular context. They are usually triggered by a shortcut or by
5+
clicking a light bulb icon in the editor. Cursor position or selection
6+
is signified by `┃` character.
7+
8+
{{#include generated.md:2:}}

0 commit comments

Comments
 (0)