Add mdbook site

README.md

@@ -3,99 +3,48 @@
 [![Task Status](https://community-tc.services.mozilla.com/api/github/v1/repository/mozilla/rust-code-analysis/master/badge.svg)](https://community-tc.services.mozilla.com/api/github/v1/repository/mozilla/rust-code-analysis/master/latest)
 [![codecov](https://codecov.io/gh/mozilla/rust-code-analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/mozilla/rust-code-analysis)
 
-**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).
-
-## Supported Languages
-
-* C++
-* C#
-* CSS
-* Go
-* HTML
-* Java
-* JavaScript
-* The JavaScript used in Firefox internal
-* Python
-* Rust
-* Typescript
-
-## Supported Metrics
-
-- CC: it calculates the code complexity examining the
-control flow of a program.
-- SLOC: it counts the number of lines in a source file.
-- PLOC: it counts the number of physical lines (instructions) contained in a source file.
-- LLOC: it counts the number of logical lines (statements) contained in a source file.
-- CLOC: it counts the number of comments in a source file.
-- BLANK: it counts the number of blank lines in a source file.
-- 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.
-- MI: it is a suite that allows to evaluate the maintainability of a software.
-- NOM: it counts the number of functions and closures in a file/trait/class.
-- NEXITS: it counts the number of possible exit points from a method/function.
-- NARGS: it counts the number of arguments of a function/method.
-
-# rust-code-analysis-cli
-
-**rust-code-analysis-cli** is a command line tool thought to interact with
-the functions available in the library.
-It can print a series of information on your shell such as nodes and metrics.
-It can also export metrics as a json file.
-Below you can find a series of commands to use the software at best.
-
-### How to get metrics
-
-You can get metrics in your shell in this way
-
-```
-rust-code-analysis-cli --metrics --paths /your/path/to/a/file
-```
-
-or as a `json` file
-
-```
-rust-code-analysis-cli --metrics --output your/path/to/the/output/directory --paths /your/path/to/a/file
-```
-
-or you can run it as a `HTTP` service and use its `REST API`
-
-
-```
-rust-code-analysis --serve --port 9090
-```
-
-
-## How to build the software
-
-Clone the repository and its submodules through HTTPS
-
-```
-git clone --recurse-submodules -j8 https://github.com/mozilla/rust-code-analysis.git
-```
-
-or through SSH
-
-```
-git clone --recurse-submodules -j8 git@github.com:mozilla/rust-code-analysis.git
-```
-
-Build and run the software
-
-```console
-# Build rust-code-analysis with cargo
-cargo build
-
-# Build rust-code-analysis-cli with cargo
-cargo build --all
-
-# Run through cargo
-cargo run -- -h
-cargo run -- --serve --port 8000
-```
-
-## How to run tests
-
-After the build step, run the following command to verify if all tests pass
-
-```
-cargo test --verbose
-```
+**rust-code-analysis** is a Rust library to analyze and extract information
+from source codes written in many different programming languages.
+It is based on a parser generator tool and an incremental parsing library
+called
+<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">
+    Tree Sitter
+</a>.
+
+
+In addition, we provide a command line tool called **rust-code-analysis-cli**
+to interact with the API of the library in an easy way.
+
+This tool can be used to:
+
+- Call **rust-code-analysis** API
+- Print nodes and metrics information
+- Export metrics in different formats
+
+# Software Usability
+
+**rust-code-analysis** supports many types of programming languages and
+computes a great variety of metrics. If you want to discover more on this
+software, read our
+<a href="https://mozilla.github.io/rust-code-analysis/index.html" target="_blank">
+    Documentation
+</a>.
+
+On the
+<a href="https://mozilla.github.io/rust-code-analysis/commands/index.html" target="_blank">
+    Commands
+</a> page, you will learn which commands need to be run to get information
+about metrics, nodes, and other general data provided by this software.
+
+If you want to contribute to the development of this software
+or you are just interested in building **rust-code-analysis**, have a look at the
+<a href="https://mozilla.github.io/rust-code-analysis/developers/index.html" target="_blank">
+    Developers Guide
+</a>.
+
+# License
+
+All the source code of **rust-code-analysis** is released under the
+<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
+    Mozilla Public License v2.0
+</a>.

rust-code-analysis-book/.gitignore

@@ -0,0 +1,3 @@
+book
+src/debug/*
+src/.rustc_info.json

rust-code-analysis-book/book.toml

@@ -0,0 +1,20 @@
+[book]
+title = "Rust-Code-Analysis Documentation"
+description = "This book documents rust-code-analysis"
+authors = ["Calixte Denizet <cdenizet@mozilla.com>"]
+language = "en"
+
+[output.html]
+mathjax-support = true
+
+[output.html.playpen]
+line-numbers = true
+
+[output.html.search]
+limit-results = 25
+use-boolean-and = true
+boost-title = 2
+boost-hierarchy = 2
+boost-paragraph = 1
+expand = true
+heading-split-level = 3

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

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+[ -d /tmp/book ] || (git worktree prune && git branch -D gh-pages)
+
+git worktree add -b gh-pages /tmp/book
+mdbook build
+rm -rf /tmp/book/* # this won't delete the .git directory
+cp -rp book/* /tmp/book/
+cd /tmp/book
+git add -A
+git commit -m "Deploy rust-code-analysis"
+git push -f origin gh-pages

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

@@ -0,0 +1,81 @@
+# rust-code-analysis
+
+**rust-code-analysis** is a Rust library to analyze and extract information
+from source codes written in many different programming languages.
+It is based on a parser generator tool and an incremental parsing library
+called
+<a href="https://tree-sitter.github.io/tree-sitter/" target="_blank">Tree Sitter</a>.
+
+You can find the source code of this software on
+<a href="https://github.com/mozilla/rust-code-analysis/" target="_blank">GitHub</a>,
+while issues and feature requests can be posted on the respective
+<a href="https://github.com/mozilla/rust-code-analysis/issues/" target="_blank">GitHub Issue Tracker</a>.
+
+## Supported Languages
+
+Below you can find the list of programming languages parsed by
+**rust-code-analysis**.
+
+* C++
+* C#
+* CSS
+* Go
+* HTML
+* Java
+* JavaScript
+* The JavaScript used in Firefox internal
+* Python
+* Rust
+* Typescript
+
+## Supported Metrics
+
+**rust-code-analysis** implements a series of metrics
+- **CC**: it calculates the code complexity examining the
+  control flow of a program.
+- **SLOC**: it counts the number of lines in a source file.
+- **PLOC**: it counts the number of physical lines (instructions) contained in
+  a source file.
+- **LLOC**: it counts the number of logical lines (statements) contained in
+  a source file.
+- **CLOC**: it counts the number of comments in a source file.
+- **BLANK**: it counts the number of blank lines in a source file.
+- **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.
+- **MI**: it is a suite that allows to evaluate the maintainability of a software.
+- **NOM**: it counts the number of functions and closures in a file/trait/class.
+- **NEXITS**: it counts the number of possible exit points from a method/function.
+- **NARGS**: it counts the number of arguments of a function/method.
+
+The metrics above are still **NOT** implemented for C#, CSS, Go, HTML, and Java
+languages.
+
+## Supported platforms
+
+**rust-code-analysis** can run on the most common platforms: Linux, macOS,
+and Windows.
+
+On our
+<a href="https://github.com/mozilla/rust-code-analysis/releases" target="_blank">
+    GitHub Release Page
+</a> you can find the `Linux` and `Windows` binaries already compiled and
+packed for you.
+
+
+## API docs
+
+If you prefer to use **rust-code-analysis** as a crate, you can find the
+`API docs` generated by `Rustdoc`
+<a href="https://docs.rs/rust-code-analysis/*/rust-code-analysis/" target="_blank">
+    here
+</a>.
+
+## License
+
+All the source code of **rust-code-analysis** is released under the
+<a href="https://www.mozilla.org/MPL/2.0/" target="_blank">
+    Mozilla Public License v2.0
+</a>.

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

@@ -0,0 +1,8 @@
+# Summary
+
+- [rust-code-analysis](./README.md)
+- [Commands](commands/README.md)
+    - [Metrics](commands/metrics.md)
+    - [Nodes](commands/nodes.md)
+    - [Rest API](commands/rest.md)
+- [Developers Guide](developers/README.md)

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

@@ -0,0 +1,64 @@
+# Commands
+
+With the term **command**, we define any procedure used by
+**rust-code-analysis-cli** to extract information from source codes.
+At each command **may** be associated parameters depending on the task
+it needs to carry out.
+In this page we have grouped the principal **types** of commands implemented in
+**rust-code-analysis-cli**.
+
+## Metrics
+
+Metrics are a series of measures that can be used to:
+
+- Compare different programming languages
+- Provide information on the quality of a code
+- Tell developers where their code is more tough to handle
+- Discover errors earlier
+
+**rust-code-analysis** calculates the metrics starting from the
+source code of a program. These kind of metrics are called *static metrics*.
+
+The list of metrics supported right now are the following ones:
+
+- **CC**: it calculates the code complexity examining the
+  control flow of a program.
+- **SLOC**: it counts the number of lines in a source file.
+- **PLOC**: it counts the number of physical lines (instructions) contained in
+  a source file.
+- **LLOC**: it counts the number of logical lines (statements) contained in
+  a source file.
+- **CLOC**: it counts the number of comments in a source file.
+- **BLANK**: it counts the number of blank lines in a source file.
+- **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.
+- **MI**: it is a suite that allows to evaluate the maintainability of a software.
+- **NOM**: it counts the number of functions and closures in a file/trait/class.
+- **NEXITS**: it counts the number of possible exit points from a method/function.
+- **NARGS**: it counts the number of arguments of a function/method.
+
+## Nodes
+
+To represent the structure of program code, **rust-code-analysis-cli** builds
+an
+<a href="https://en.wikipedia.org/wiki/Abstract_syntax_tree" target="_blank">Abstract Syntax Tree (AST)</a>.
+A **node** is an element of this tree and denotes any syntactic construct
+present in a language.
+
+Nodes can be used to:
+
+- Create the syntactic structure of a source file
+- Discover if a construct of a language is present in the analyzed
+  code
+- Count the number of constructs of a certain kind
+- Detect errors i the source code
+
+## REST API
+
+**rust-code-analysis-cli** can be run as a server which accepts requests sent
+through `REST API`.
+The server receives in input the filename of a source code file and returns the
+relative metrics formatted as a `json` file.

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

@@ -0,0 +1,54 @@
+# Metrics
+
+Metrics can be printed on screen or exported as different output formats
+through **rust-code-analysis-cli**.
+
+## Print metrics
+
+For each function space, **rust-code-analysis** computes the list of metrics
+described above. At the end of this process, **rust-code-analysis-cli**
+dumps the result formatted in a certain way on the screen.
+The command used to print the metrics is the following one:
+
+```console
+rust-code-analysis-cli -m -p /path/to/your/file/or/directory
+```
+
+The `-p` option represents the path to a file or a directory. If a directory is
+passed as input, **rust-code-analysis-cli** computes the metrics for each file
+contained in it.
+
+## Export formats
+
+Different output formats can be used to export metrics:
+
+- Cbor
+- Json
+- Toml
+- Yaml
+
+`Json` and `Toml` can also be exported pretty-printed.
+
+### Export command
+
+For example, if you want to export metrics as a `json` file, run:
+
+```console
+rust-code-analysis-cli -m -O json -o /output/path -p /path/to/your/file/or/directory
+```
+
+The `-O` option allows you to choose the output format. It supports
+**only** these values: *cbor*, *json*, *toml*, *yaml*.
+
+The `-o` option is used to specify the path where your file will be saved.
+It accepts **only** paths. The filename of your output file is the same as
+your input file plus the extension associated to the format. When this option
+is not given, the output is printed on shell.
+
+As we said before, `Json` and `Toml` can be exported as pretty-printed. To do
+so, the `--pr` option is used.
+In the case below, the pretty-printed `json` output will be printed on shell:
+
+```console
+rust-code-analysis-cli -m -O json --pr -p /path/to/your/file/or/directory
+```