docs: Prepared Prerequisites, Command line mode and Configuration pag…

…es (#597) * docs: Add pages for Single scan for PR and local files Signed-off-by: Oleg Kopysov <[email protected]> * docs: Add Database description page Signed-off-by: Oleg Kopysov <[email protected]> * docs: Add Database customization and Config options pages Signed-off-by: Oleg Kopysov <[email protected]> * docs: Add Build and run, DB configuration, Scanner installation pages Signed-off-by: Oleg Kopysov <[email protected]> * fix: Fix Integration page Signed-off-by: Oleg Kopysov <[email protected]> --------- Signed-off-by: Oleg Kopysov <[email protected]>
Samsung · Sep 6, 2024 · 5485f13 · 5485f13
1 parent 99b2fb7
commit 5485f13
Show file tree

Hide file tree

Showing 12 changed files with 657 additions and 400 deletions.
diff --git a/doc/docs/css/mkdocsoad.css b/doc/docs/css/mkdocsoad.css
@@ -0,0 +1,191 @@
+/**
+ *   CSS for OpenAPI HTML generated with PyMdown Extensions option.
+ *
+ *   This CSS file works when using the OAD plugin with pymdownx.
+ *   See here how to use it:
+ *   https://www.neoteroi.dev/mkdocs-plugins/web/oad/
+ *
+ *   https://github.com/Neoteroi/mkdocs-plugins
+**/
+
+:root {
+    --http-get-color: green;
+    --http-delete-color: #dc0101;
+    --http-head-color: slateblue;
+    --http-options-color: steelblue;
+    --http-patch-color: darkorange;
+    --http-post-color: darkblue;
+    --http-put-color: darkmagenta;
+    --http-trace-color: darkcyan;
+    --http-route-param-color: rgb(51, 128, 210);
+    --oad-operation-separator-border-color: gray;
+    --oad-block-border-color: #00bfa5;
+    --oad-small-note-color: #666;
+    --oad-indent-border-color: #c5c5c5;
+}
+
+@media screen {
+    /* Slate theme, i.e. dark mode */
+    [data-md-color-scheme="slate"] {
+        --http-get-color: #2ea82e;
+        --http-post-color: #0093c0;
+        --http-put-color: #c333c3;
+        --oad-small-note-color: #afafaf;
+    }
+}
+
+.api-tag {
+    font-weight: bold;
+}
+
+span[class^="http-"] {
+    font-weight: bold;
+    color: #fff;
+    padding: 4px 1rem;
+    border-radius: 2px;
+    margin-right: .5rem;
+}
+
+.http-get {
+    background-color: var(--http-get-color);
+}
+
+.http-delete {
+    background-color: var(--http-delete-color);
+}
+
+.http-post {
+    background-color: var(--http-post-color);
+}
+
+.http-patch {
+    background-color: var(--http-patch-color);
+}
+
+.http-trace {
+    background-color: var(--http-trace-color);
+}
+
+.http-put {
+    background-color: var(--http-put-color);
+}
+
+.http-head {
+    background-color: var(--http-head-color);
+}
+
+.http-options {
+    background-color: var(--http-options-color);
+}
+
+.route-param {
+    color: var(--http-route-param-color);
+}
+
+.operation-separator + h3[id^="get"] .route-param {
+    color: var(--http-get-color);
+}
+
+.operation-separator + h3[id^="delete"] .route-param {
+    color: var(--http-delete-color);
+}
+
+
+.operation-separator + h3[id^="post"] .route-param {
+    color: var(--http-post-color);
+}
+
+.operation-separator + h3[id^="patch"] .route-param {
+    color: var(--http-patch-color);
+}
+
+.operation-separator + h3[id^="trace"] .route-param {
+    color: var(--http-trace-color);
+}
+
+.operation-separator + h3[id^="put"] .route-param {
+    color: var(--http-put-color);
+}
+
+.operation-separator + h3[id^="head"] .route-param {
+    color: var(--http-head-color);
+}
+
+.operation-separator + h3[id^="options"] .route-param {
+    color: var(--http-options-color);
+}
+
+.api-version {
+    font-size: 1.2rem;
+}
+
+.operation-separator {
+    margin: 0 !important;
+    border-bottom: 2px dotted var(--oad-operation-separator-border-color) !important;
+    padding-top: .5rem;
+}
+
+.operation-separator + h3 {
+    margin-top: 1rem;
+}
+
+.string-type {
+    color: var(--md-code-hl-string-color);
+}
+
+.integer-type, .number-type {
+    color: var(--md-code-hl-number-color);
+}
+
+.boolean-type {
+    color: var(--md-code-hl-keyword-color);
+}
+
+.format {
+    color: var(--md-code-hl-name-color);
+}
+
+.null-type {
+    color: var(--md-code-hl-keyword-color);
+}
+
+a.ref-link {
+    color: var(--md-code-hl-special-color);
+}
+
+.request-block + div {
+    padding-left: 1rem;
+    border-left: 2px dashed var(--oad-block-border-color);
+}
+
+.small-note {
+    font-size: 14px;
+    color: var(--oad-small-note-color);
+}
+
+.request-body-title {
+    margin-bottom: 4px;
+}
+
+.request-body-title + .tabbed-set,
+.response-title + .tabbed-set,
+.message-separator + .tabbed-set,
+.common-response,
+.response-section {
+    margin-top: 2px;
+    padding-left: 1rem;
+    border-left: 2px dotted var(--oad-indent-border-color);
+}
+
+.info-data {
+    font-size: .6rem;
+}
+
+.message-separator {
+    visibility: hidden;
+}
+
+.sub-section-title {
+    font-style: italic;
+    font-size: 14px;
+}
diff --git a/doc/docs/dev-guide/integration.md b/doc/docs/dev-guide/integration.md
@@ -4,7 +4,7 @@ Use of LPVS JAR in your project
 
 ---
 
-## 1. Authenticating with a personal access token
+## Authenticating with a personal access token
 
 You can authenticate to GitHub Packages with Apache Maven by editing your 
 `~/.m2/settings.xml` file to include your personal access token.
@@ -60,12 +60,12 @@ Example `settings.xml`:
 
 !!! note
 
-    if your `settings.xml` file is not located in `~/.m2/settings.xml`, then you need 
+    If your `settings.xml` file is not located in `~/.m2/settings.xml`, then you need 
     to add the `-s path/to/file/settings.xml` option to `mvn` command
 
 ---
 
-## 2 Installing a package
+## Installing a package
 
 Edit the `<dependencies>` element of the `pom.xml` file located in your project directory.
 

diff --git a/doc/docs/user-guide/README.md b/doc/docs/user-guide/README.md
@@ -14,26 +14,18 @@ There are 2 modes of LPVS operation:
 
 ## Service mode
 
-- [GitHub webhook configuration]
-- [Run service using pre-built Docker image]
-- [Build and run service from the source code]
+- [GitHub webhook configuration](service/webhook.md)
+- [Run service using pre-built Docker image](service/docker.md)
+- [Scanner installation](service/scanner.md)
+- [Database configuration](service/database.md)
+- [Build and run service from the source code](service/build-and-run.md)
 
 ## Command line mode
 
-- [Single scan of the pull request]
-- [Single scan of local files]
+- [Single scan of the pull request](cli/cli_pr.md)
+- [Single scan of local files](cli/cli_file.md)
 
-## Configuration options
+## Configuration
 
-- [Possible configuration options]
-- [Database with licenses and license conflicts]
-
-[GitHub webhook configuration]: service/webhook.md
-[Run service using pre-built Docker image]: service/docker.md
-[Build and run service from the source code]: service/source_code.md
-
-[Single scan of the pull request]: cli/cli_pr.md
-[Single scan of local files]: cli/cli_file.md
-
-[Possible configuration options]: config/options.md
-[Database with licenses and license conflicts]: config/database.md
+- [Configuration options](config/options.md)
+- [Database customization](config/database.md)
diff --git a/doc/docs/user-guide/cli/cli_file.md b/doc/docs/user-guide/cli/cli_file.md
@@ -0,0 +1,64 @@
+# Single scan of local files
+
+One-time scan on a specific local files from the command line.
+
+---
+
+You can perform a one-time scan on a specific local file or folder using the single scan mode.
+LPVS should be compiled from the source code. Please refer to the [detailed guideline](../../user-guide/service/build-and-run.md).
+
+Follow the next steps:
+
+* Make sure that the ScanOSS scanner is installed. If not, please follow 
+  the [installation guide](../../user-guide/service/scanner.md).
+
+* Fill in all required properties in the profile file. Please refer to
+  the [profile configuration guide](../config/options.md).
+
+* Build and install LPVS, navigate to the target directory. For more details,
+  please refer to the [build instructions](../service/build-and-run.md).
+
+```bash
+mvn clean install
+cd target/
+```
+
+* Choose a specific local file or folder which is a target for the scan and run the command with flag `--local.path`:
+
+```bash
+java -jar lpvs-*.jar --local.path=</path/to/file/or/folder>
+```
+
+Example:
+
+```bash
+-jar lpvs-*.jar --local.path=test.java
+```
+
+!!! note
+
+    By default, the above commands require a [pre-configured MySQL database](../../user-guide/service/database.md). 
+    Use the "singlescan" profile to skip setting up a pre-configured MySQL database:
+
+    ```bash
+    java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --local.path=</path/to/file/or/folder>
+    ```
+
+* Optionally, generate an HTML report and save it in a specified folder using flag `--build.html.report`.
+  Replace `path/to/your/folder` with the full path to the folder where you want to save the HTML report,
+  and `your_report_filename.html` with the desired filename for the report.
+
+```bash
+java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --local.path=</path/to/file/or/folder> --build.html.report=<your_report_filename.html>
+```
+
+!!! warning
+
+    Ensure that the specified folder exists before generating the HTML report.
+
+Examples of the command:
+
+```bash
+java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --local.path=test.c
+java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --local.path=test_folder --build.html.report=test/report.html
+```
diff --git a/doc/docs/user-guide/cli/cli_pr.md b/doc/docs/user-guide/cli/cli_pr.md
@@ -0,0 +1,64 @@
+# Single scan of the pull request
+
+One-time scan on a specific pull request from the command line.
+
+---
+
+You can perform a one-time scan on a specific pull request using the single scan mode. 
+LPVS should be compiled from the source code. Please refer to the [detailed guideline](../../user-guide/service/build-and-run.md).
+
+Follow the next steps:
+
+* Make sure that the ScanOSS scanner is installed. If not, please follow
+  the [installation guide](../../user-guide/service/scanner.md).
+
+* Fill in all required properties in the profile file. Please refer to
+  the [profile configuration guide](../config/options.md).
+
+* Build and install LPVS, navigate to the target directory. For more details,
+  please refer to the [build instructions](../service/build-and-run.md).
+
+```bash
+mvn clean install
+cd target/
+```
+
+* Choose a specific pull request from GitHub which is a target for the scan and run the command with flag `--github.pull.request`:
+
+```bash
+java -jar -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL>
+```
+
+Example: 
+
+```bash
+-jar -Dgithub.token=your_personal_token lpvs-*.jar --github.pull.request=https://github.com/Samsung/LPVS/pull/594
+```
+
+!!! note
+
+    By default, the above commands require a [pre-configured MySQL database](../../user-guide/service/database.md). 
+    Use the "singlescan" profile to skip setting up a pre-configured MySQL database:
+
+    ```bash
+    java -jar -Dspring.profiles.active=singlescan -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL>
+    ```
+
+* Optionally, generate an HTML report and save it in a specified folder using flag `--build.html.report`. 
+Replace `path/to/your/folder` with the full path to the folder where you want to save the HTML report, 
+and `your_report_filename.html` with the desired filename for the report.
+
+```bash
+java -jar -Dspring.profiles.active=singlescan -Dgithub.token=<my-token> lpvs-*.jar --github.pull.request=<PR URL> --build.html.report=</path/to/your/folder/your_report_filename.html>
+```
+
+!!! warning
+
+    Ensure that the specified folder exists before generating the HTML report.
+
+Examples of the command:
+
+```bash
+java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --github.pull.request=https://github.com/Samsung/LPVS/pull/2
+java -jar -Dspring.profiles.active=singlescan lpvs-*.jar --github.pull.request=https://github.com/Samsung/LPVS/pull/2 --build.html.report=report.html
+```