Skip to content

Commit c411a7a

Browse files
Luni-4Luni-4
authored
Add mdbook site (#176)
* Add mdbook * Add a script to automatically deploy Github Pages * Update README * Add link to documentation * Clarify a statement * Refactor Rest API page * Add a section to explain how to count errors
1 parent 9c723f0 commit c411a7a

11 files changed

Lines changed: 506 additions & 96 deletions

File tree

‎README.md‎

Lines changed: 45 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -6,99 +6,48 @@
66
<img src="https://img.shields.io/badge/chat%20on%20[m]-%23rust--code--analysis%3Amozilla.org-blue">
77
</a>
88

9-
**rust-code-analysis** is a Rust library to analyze the source code of many different programming languages. It is based on a parser generator tool and an incremental parsing library called [Tree Sitter](https://github.com/tree-sitter/tree-sitter).
10-
11-
## Supported Languages
12-
13-
* C++
14-
* C#
15-
* CSS
16-
* Go
17-
* HTML
18-
* Java
19-
* JavaScript
20-
* The JavaScript used in Firefox internal
21-
* Python
22-
* Rust
23-
* Typescript
24-
25-
## Supported Metrics
26-
27-
- CC: it calculates the code complexity examining the
28-
control flow of a program.
29-
- SLOC: it counts the number of lines in a source file.
30-
- PLOC: it counts the number of physical lines (instructions) contained in a source file.
31-
- LLOC: it counts the number of logical lines (statements) contained in a source file.
32-
- CLOC: it counts the number of comments in a source file.
33-
- BLANK: it counts the number of blank lines in a source file.
34-
- HALSTEAD: it is a suite that provides a series of information, such as the effort required to maintain the analyzed code, the size in bits to store the program, the difficulty to understand the code, an estimate of the number of bugs present in the codebase, and an estimate of the time needed to implement the software.
35-
- MI: it is a suite that allows to evaluate the maintainability of a software.
36-
- NOM: it counts the number of functions and closures in a file/trait/class.
37-
- NEXITS: it counts the number of possible exit points from a method/function.
38-
- NARGS: it counts the number of arguments of a function/method.
39-
40-
# rust-code-analysis-cli
41-
42-
**rust-code-analysis-cli** is a command line tool thought to interact with
43-
the functions available in the library.
44-
It can print a series of information on your shell such as nodes and metrics.
45-
It can also export metrics as a json file.
46-
Below you can find a series of commands to use the software at best.
47-
48-
### How to get metrics
49-
50-
You can get metrics in your shell in this way
51-
52-
```
53-
rust-code-analysis-cli --metrics --paths /your/path/to/a/file
54-
```
55-
56-
or as a `json` file
57-
58-
```
59-
rust-code-analysis-cli --metrics --output your/path/to/the/output/directory --paths /your/path/to/a/file
60-
```
61-
62-
or you can run it as a `HTTP` service and use its `REST API`
63-
64-
65-
```
66-
rust-code-analysis --serve --port 9090
67-
```
68-
69-
70-
## How to build the software
71-
72-
Clone the repository and its submodules through HTTPS
73-
74-
```
75-
git clone --recurse-submodules -j8 https://github.com/mozilla/rust-code-analysis.git
76-
```
77-
78-
or through SSH
79-
80-
```
81-
git clone --recurse-submodules -j8 git@github.com:mozilla/rust-code-analysis.git
82-
```
83-
84-
Build and run the software
85-
86-
```console
87-
# Build rust-code-analysis with cargo
88-
cargo build
89-
90-
# Build rust-code-analysis-cli with cargo
91-
cargo build --all
92-
93-
# Run through cargo
94-
cargo run -- -h
95-
cargo run -- --serve --port 8000
96-
```
97-
98-
## How to run tests
99-
100-
After the build step, run the following command to verify if all tests pass
101-
102-
```
103-
cargo test --verbose
104-
```
9+
**rust-code-analysis** is a Rust library to analyze and extract information
10+
from source codes written in many different programming languages.
11+
It is based on a parser generator tool and an incremental parsing library
12+
called
13+
<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">
14+
Tree Sitter
15+
</a>.
16+
17+
18+
In addition, we provide a command line tool called **rust-code-analysis-cli**
19+
to interact with the API of the library in an easy way.
20+
21+
This tool can be used to:
22+
23+
- Call **rust-code-analysis** API
24+
- Print nodes and metrics information
25+
- Export metrics in different formats
26+
27+
# Software Usability
28+
29+
**rust-code-analysis** supports many types of programming languages and
30+
computes a great variety of metrics. If you want to discover more on this
31+
software, read our
32+
<a href="https://mozilla.github.io/rust-code-analysis/index.html" target="_blank">
33+
Documentation
34+
</a>.
35+
36+
On the
37+
<a href="https://mozilla.github.io/rust-code-analysis/commands/index.html" target="_blank">
38+
Commands
39+
</a> page, you will learn which commands need to be run to get information
40+
about metrics, nodes, and other general data provided by this software.
41+
42+
If you want to contribute to the development of this software
43+
or you are just interested in building **rust-code-analysis**, have a look at the
44+
<a href="https://mozilla.github.io/rust-code-analysis/developers/index.html" target="_blank">
45+
Developers Guide
46+
</a>.
47+
48+
# License
49+
50+
All the source code of **rust-code-analysis** is released under the
51+
<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
52+
Mozilla Public License v2.0
53+
</a>.

‎rust-code-analysis-book/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
book
2+
src/debug/*
3+
src/.rustc_info.json

‎rust-code-analysis-book/book.toml‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
[book]
2+
title = "Rust-Code-Analysis Documentation"
3+
description = "This book documents rust-code-analysis"
4+
authors = ["Calixte Denizet <cdenizet@mozilla.com>"]
5+
language = "en"
6+
7+
[output.html]
8+
mathjax-support = true
9+
10+
[output.html.playpen]
11+
line-numbers = true
12+
13+
[output.html.search]
14+
limit-results = 25
15+
use-boolean-and = true
16+
boost-title = 2
17+
boost-hierarchy = 2
18+
boost-paragraph = 1
19+
expand = true
20+
heading-split-level = 3

‎rust-code-analysis-book/deploy-to-GitHub-Pages‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
#!/bin/sh
2+
3+
[ -d /tmp/book ] || (git worktree prune && git branch -D gh-pages)
4+
5+
git worktree add -b gh-pages /tmp/book
6+
mdbook build
7+
rm -rf /tmp/book/* # this won't delete the .git directory
8+
cp -rp book/* /tmp/book/
9+
cd /tmp/book
10+
git add -A
11+
git commit -m "Deploy rust-code-analysis"
12+
git push -f origin gh-pages

‎rust-code-analysis-book/src/README.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# rust-code-analysis
2+
3+
**rust-code-analysis** is a Rust library to analyze and extract information
4+
from source codes written in many different programming languages.
5+
It is based on a parser generator tool and an incremental parsing library
6+
called
7+
<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">Tree Sitter</a>.
8+
9+
You can find the source code of this software on
10+
<a href="https://github.com/mozilla/rust-code-analysis/" target="_blank">GitHub</a>,
11+
while issues and feature requests can be posted on the respective
12+
<a href="https://github.com/mozilla/rust-code-analysis/issues/" target="_blank">GitHub Issue Tracker</a>.
13+
14+
## Supported Languages
15+
16+
Below you can find the list of programming languages parsed by
17+
**rust-code-analysis**.
18+
19+
* C++
20+
* C#
21+
* CSS
22+
* Go
23+
* HTML
24+
* Java
25+
* JavaScript
26+
* The JavaScript used in Firefox internal
27+
* Python
28+
* Rust
29+
* Typescript
30+
31+
## Supported Metrics
32+
33+
**rust-code-analysis** implements a series of metrics
34+
- **CC**: it calculates the code complexity examining the
35+
control flow of a program.
36+
- **SLOC**: it counts the number of lines in a source file.
37+
- **PLOC**: it counts the number of physical lines (instructions) contained in
38+
a source file.
39+
- **LLOC**: it counts the number of logical lines (statements) contained in
40+
a source file.
41+
- **CLOC**: it counts the number of comments in a source file.
42+
- **BLANK**: it counts the number of blank lines in a source file.
43+
- **HALSTEAD**: it is a suite that provides a series of information, such as the
44+
effort required to maintain the analyzed code, the size in bits to store the
45+
program, the difficulty to understand the code, an estimate of the number of
46+
bugs present in the codebase, and an estimate of the time needed to
47+
implement the software.
48+
- **MI**: it is a suite that allows to evaluate the maintainability of a software.
49+
- **NOM**: it counts the number of functions and closures in a file/trait/class.
50+
- **NEXITS**: it counts the number of possible exit points from a method/function.
51+
- **NARGS**: it counts the number of arguments of a function/method.
52+
53+
The metrics above are still **NOT** implemented for C#, CSS, Go, HTML, and Java
54+
languages.
55+
56+
## Supported platforms
57+
58+
**rust-code-analysis** can run on the most common platforms: Linux, macOS,
59+
and Windows.
60+
61+
On our
62+
<a href="https://github.com/mozilla/rust-code-analysis/releases" target="_blank">
63+
GitHub Release Page
64+
</a> you can find the `Linux` and `Windows` binaries already compiled and
65+
packed for you.
66+
67+
68+
## API docs
69+
70+
If you prefer to use **rust-code-analysis** as a crate, you can find the
71+
`API docs` generated by `Rustdoc`
72+
<a href="https://docs.rs/rust-code-analysis/*/rust-code-analysis/" target="_blank">
73+
here
74+
</a>.
75+
76+
## License
77+
78+
All the source code of **rust-code-analysis** is released under the
79+
<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
80+
Mozilla Public License v2.0
81+
</a>.

‎rust-code-analysis-book/src/SUMMARY.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Summary
2+
3+
- [rust-code-analysis](./README.md)
4+
- [Commands](commands/README.md)
5+
- [Metrics](commands/metrics.md)
6+
- [Nodes](commands/nodes.md)
7+
- [Rest API](commands/rest.md)
8+
- [Developers Guide](developers/README.md)

‎rust-code-analysis-book/src/commands/README.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Commands
2+
3+
With the term **command**, we define any procedure used by
4+
**rust-code-analysis-cli** to extract information from source codes.
5+
At each command **may** be associated parameters depending on the task
6+
it needs to carry out.
7+
In this page we have grouped the principal **types** of commands implemented in
8+
**rust-code-analysis-cli**.
9+
10+
## Metrics
11+
12+
Metrics are a series of measures that can be used to:
13+
14+
- Compare different programming languages
15+
- Provide information on the quality of a code
16+
- Tell developers where their code is more tough to handle
17+
- Discover errors earlier
18+
19+
**rust-code-analysis** calculates the metrics starting from the
20+
source code of a program. These kind of metrics are called *static metrics*.
21+
22+
The list of metrics supported right now are the following ones:
23+
24+
- **CC**: it calculates the code complexity examining the
25+
control flow of a program.
26+
- **SLOC**: it counts the number of lines in a source file.
27+
- **PLOC**: it counts the number of physical lines (instructions) contained in
28+
a source file.
29+
- **LLOC**: it counts the number of logical lines (statements) contained in
30+
a source file.
31+
- **CLOC**: it counts the number of comments in a source file.
32+
- **BLANK**: it counts the number of blank lines in a source file.
33+
- **HALSTEAD**: it is a suite that provides a series of information, such as the
34+
effort required to maintain the analyzed code, the size in bits to store the
35+
program, the difficulty to understand the code, an estimate of the number of
36+
bugs present in the codebase, and an estimate of the time needed to
37+
implement the software.
38+
- **MI**: it is a suite that allows to evaluate the maintainability of a software.
39+
- **NOM**: it counts the number of functions and closures in a file/trait/class.
40+
- **NEXITS**: it counts the number of possible exit points from a method/function.
41+
- **NARGS**: it counts the number of arguments of a function/method.
42+
43+
## Nodes
44+
45+
To represent the structure of program code, **rust-code-analysis-cli** builds
46+
an
47+
<a href="https://en.wikipedia.org/wiki/Abstract_syntax_tree" target="_blank">Abstract Syntax Tree (AST)</a>.
48+
A **node** is an element of this tree and denotes any syntactic construct
49+
present in a language.
50+
51+
Nodes can be used to:
52+
53+
- Create the syntactic structure of a source file
54+
- Discover if a construct of a language is present in the analyzed
55+
code
56+
- Count the number of constructs of a certain kind
57+
- Detect errors i the source code
58+
59+
## REST API
60+
61+
**rust-code-analysis-cli** can be run as a server which accepts requests sent
62+
through `REST API`.
63+
The server receives in input the filename of a source code file and returns the
64+
relative metrics formatted as a `json` file.

‎rust-code-analysis-book/src/commands/metrics.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Metrics
2+
3+
Metrics can be printed on screen or exported as different output formats
4+
through **rust-code-analysis-cli**.
5+
6+
## Print metrics
7+
8+
For each function space, **rust-code-analysis** computes the list of metrics
9+
described above. At the end of this process, **rust-code-analysis-cli**
10+
dumps the result formatted in a certain way on the screen.
11+
The command used to print the metrics is the following one:
12+
13+
```console
14+
rust-code-analysis-cli -m -p /path/to/your/file/or/directory
15+
```
16+
17+
The `-p` option represents the path to a file or a directory. If a directory is
18+
passed as input, **rust-code-analysis-cli** computes the metrics for each file
19+
contained in it.
20+
21+
## Export formats
22+
23+
Different output formats can be used to export metrics:
24+
25+
- Cbor
26+
- Json
27+
- Toml
28+
- Yaml
29+
30+
`Json` and `Toml` can also be exported pretty-printed.
31+
32+
### Export command
33+
34+
For example, if you want to export metrics as a `json` file, run:
35+
36+
```console
37+
rust-code-analysis-cli -m -O json -o /output/path -p /path/to/your/file/or/directory
38+
```
39+
40+
The `-O` option allows you to choose the output format. It supports
41+
**only** these values: *cbor*, *json*, *toml*, *yaml*.
42+
43+
The `-o` option is used to specify the path where your file will be saved.
44+
It accepts **only** paths. The filename of your output file is the same as
45+
your input file plus the extension associated to the format. When this option
46+
is not given, the output is printed on shell.
47+
48+
As we said before, `Json` and `Toml` can be exported as pretty-printed. To do
49+
so, the `--pr` option is used.
50+
In the case below, the pretty-printed `json` output will be printed on shell:
51+
52+
```console
53+
rust-code-analysis-cli -m -O json --pr -p /path/to/your/file/or/directory
54+
```

0 commit comments

Comments
 (0)