From 6297041f73d06910b9ea992f9005122bc74b35d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1rton=20Csord=C3=A1s?= Date: Tue, 19 Jan 2021 14:58:48 +0100 Subject: [PATCH] [doc] Using details/summary in md files to show help message The documentation files contain a lot command line help messages in raw format and this way it is hard to read the docs. For this reason with this patch we will use the HTML5 details feature which will collapse the help messages by default and it will not take up so much space. --- .../merge_clang_extdef_mappings/README.md | 8 +- analyzer/tools/statistics_collector/README.md | 8 +- docs/analyzer/user_guide.md | 42 ++++++++++ docs/web/authentication.md | 23 ++++++ docs/web/products.md | 11 +++ docs/web/user_guide.md | 78 ++++++++++++++++++- tools/plist_to_html/README.md | 8 +- tools/report-converter/README.md | 6 +- tools/tu_collector/README.md | 8 +- 9 files changed, 186 insertions(+), 6 deletions(-) diff --git a/analyzer/tools/merge_clang_extdef_mappings/README.md b/analyzer/tools/merge_clang_extdef_mappings/README.md index e7ad45b10e..878fe2046f 100644 --- a/analyzer/tools/merge_clang_extdef_mappings/README.md +++ b/analyzer/tools/merge_clang_extdef_mappings/README.md @@ -22,7 +22,12 @@ make package ``` ## Usage -```sh +
+ + $ merge-clang-extdef-mappings --help (click to expand) + + +``` usage: merge-clang-extdef-mappings [-h] -i input -o output Merge individual clang extdef mapping files into one mapping file. @@ -40,6 +45,7 @@ Example: merge-clang-extdef-mappings -i /path/to/fn_map_folder -o /path/to/externalDefMap.txt ``` +
## License diff --git a/analyzer/tools/statistics_collector/README.md b/analyzer/tools/statistics_collector/README.md index 03518f906b..2bffcecd33 100644 --- a/analyzer/tools/statistics_collector/README.md +++ b/analyzer/tools/statistics_collector/README.md @@ -16,7 +16,12 @@ make package ``` ## Usage -```sh +
+ + $ post-process-stats --help (click to expand) + + +``` usage: post-process-stats [-h] -i folder [--stats-min-sample-count STATS_MIN_SAMPLE_COUNT] [--stats-relevance-threshold STATS_RELEVANCE_THRESHOLD] @@ -50,6 +55,7 @@ optional arguments: Example: post-process-stats -i /path/to/pre_processed_stats /path/to/stats ``` +
## License diff --git a/docs/analyzer/user_guide.md b/docs/analyzer/user_guide.md index b2047b915d..f2d9de3d90 100644 --- a/docs/analyzer/user_guide.md +++ b/docs/analyzer/user_guide.md @@ -86,6 +86,11 @@ _User guide_) for information about the arguments which are not documented here. For example the CTU related arguments are documented at `analyze` subcommand. +
+ + $ CodeChecker check --help (click to expand) + + ``` usage: CodeChecker check [-h] [-o OUTPUT_DIR] [-t {plist}] [-q] [--keep-gcc-include-fixed] [--keep-gcc-intrin] @@ -459,6 +464,7 @@ command actually builds the files -- it is advised to execute builds on empty trees, aka. after a 'make clean', as CodeChecker only analyzes files that had been used by the build system. ``` +
# Available CodeChecker analyzer subcommands @@ -469,6 +475,11 @@ information about the files in your project for the analyzers. This is done by recording a build of your project, which is done by the command `CodeChecker log`. +
+ + $ CodeChecker log --help (click to expand) + + ``` usage: CodeChecker log [-h] -o LOGFILE -b COMMAND [-q] [--verbose {info,debug,debug_analyzer}] @@ -529,6 +540,7 @@ Environment variables a 'codechecker.logger.debug' file beside the log file. ``` +
Please note, that only the files that are used in the given `--build` argument will be recorded. To analyze your whole project, make sure your build tree has @@ -727,6 +739,11 @@ CodeChecker analyze ../codechecker_myProject_build.log -o my_plists `CodeChecker analyze` supports a myriad of fine-tuning arguments, explained below: +
+ + $ CodeChecker analyze --help (click to expand) + + ``` usage: CodeChecker analyze [-h] [-j JOBS] [-i SKIPFILE | --file FILE [FILE ...]] -o @@ -854,6 +871,7 @@ Environment variables CC_SEVERITY_MAP_FILE Path of the checker-severity mapping config file. Default: /config/checker_severity_map.json ``` +
### _Skip_ file @@ -1478,6 +1496,11 @@ Statistics analysis feature arguments: (such as `plist` files), usually previously generated by `CodeChecker analyze`. `parse` prints analysis results to the standard output. +
+ + $ CodeChecker parse --help (click to expand) + + ``` Usage: CodeChecker parse [-h] [--config CONFIG_FILE] [-t {plist}] [-e {html,json,codeclimate,gerrit}] [-o OUTPUT_PATH] @@ -1566,6 +1589,7 @@ Environment variables generating gerrit output. Default: /config/checker_severity_map.json ``` +
For example, if the analysis was run like: @@ -1587,6 +1611,11 @@ For example there is a ClangTidy checker which suggests using simple changes can be applied directy in the source code. `CodeChecker fixit` command handles these automatic fixes. +
+ + $ CodeChecker fixit --help (click to expand) + + ``` usage: CodeChecker fixit [-h] [-l] [--checker-name [CHECKER_NAME [CHECKER_NAME...]]] @@ -1626,6 +1655,7 @@ optional arguments: --verbose {info,debug,debug_analyzer} Set verbosity level. ``` +
## `checkers` @@ -1635,6 +1665,11 @@ performing an analysis. By default, `CodeChecker checkers` will list all checkers, one per each row, providing a quick overview on which checkers are available in the analyzers. +
+ + $ CodeChecker checkers --help (click to expand) + + ``` usage: CodeChecker checkers [-h] [--analyzers ANALYZER [ANALYZER ...]] [--details] [--profile {PROFILE/list}] @@ -1687,6 +1722,7 @@ Environment variables CC_PROFILE_MAP_FILE Path of the checker-profile mapping config file. Default: '/config/checker_profile_map.json' ``` +
The list provided by default is formatted for easy machine and human reading. Use the `--only-` options (`--only-enabled` and `--only-disabled`) to @@ -1721,6 +1757,11 @@ information. By default, this command only lists the names of the available analyzers (with respect to the environment CodeChecker is run in). +
+ + $ CodeChecker analyzers --help (click to expand) + + ``` usage: CodeChecker analyzers [-h] [--all] [--details] [--dump-config {clang-tidy,clangsa}] @@ -1755,6 +1796,7 @@ optional arguments: --verbose {info,debug_analyzer,debug} Set verbosity level. ``` +
A detailed view of the available analyzers is available via `--details`. In the *detailed view*, version string and install path is also printed. diff --git a/docs/web/authentication.md b/docs/web/authentication.md index ca09ed364c..f6ef7467d6 100644 --- a/docs/web/authentication.md +++ b/docs/web/authentication.md @@ -342,6 +342,11 @@ by using the package's `config/session_client.json` as an example. > access this file. Executing `chmod 0600 ~/.codechecker.passwords.json` will > limit access to your user only. +
+ + $ CodeChecker cmd login --help (click to expand) + + ``` usage: CodeChecker cmd login [-h] [-d] [--url SERVER_URL] [--verbose {info,debug,debug_analyzer}] @@ -365,6 +370,7 @@ common arguments: --verbose {info,debug,debug_analyzer} Set verbosity level. ``` +
The user can log in onto the server by issuing the command `CodeChecker cmd login `. After receiving an *Authentication successful!* message, @@ -457,6 +463,11 @@ Personal tokens can be written instead of the user's password in the ``` ## New personal access token +
+ + $ CodeChecker cmd token new --help (click to expand) + + ``` usage: CodeChecker cmd token new [-h] [--description DESCRIPTION] [--url SERVER_URL] @@ -470,8 +481,13 @@ optional arguments: A custom textual description to be shown alongside the token. ``` +
## List personal access tokens +
+ + $ CodeChecker cmd token list --help (click to expand) + ``` usage: CodeChecker cmd token list [-h] [--url SERVER_URL] @@ -484,8 +500,14 @@ List the available personal access tokens. optional arguments: -h, --help show this help message and exit ``` +
## Remove personal access token +
+ + $ CodeChecker cmd token del --help (click to expand) + + ``` usage: CodeChecker cmd token del [-h] [--url SERVER_URL] [--verbose {info,debug,debug_analyzer}] @@ -496,3 +518,4 @@ Removes the specified access token. positional arguments: TOKEN Personal access token which will be deleted. ``` +
diff --git a/docs/web/products.md b/docs/web/products.md index a83a049bf8..6a529977cb 100644 --- a/docs/web/products.md +++ b/docs/web/products.md @@ -110,6 +110,11 @@ common arguments: `add` assigns the unique `PRODUCT_NAME` endpoint with a database connection, making a new product available on the server. +
+ + $ CodeChecker cmd products add --help (click to expand) + + ``` usage: CodeChecker cmd products add [-h] [-n DISPLAY_NAME] [--description DESCRIPTION] @@ -166,8 +171,13 @@ PostgreSQL arguments: --dbname DBNAME, --db-name DBNAME Name of the database to use. (default: ) ``` +
## Delete a product (`del`) +
+ + $ CodeChecker cmd token new --help (click to expand) + ``` usage: CodeChecker cmd products del [-h] [--url SERVER_URL] @@ -186,6 +196,7 @@ positional arguments: optional arguments: -h, --help show this help message and exit ``` +
# Managing products through the web interface diff --git a/docs/web/user_guide.md b/docs/web/user_guide.md index 02e385216e..835e1fc542 100644 --- a/docs/web/user_guide.md +++ b/docs/web/user_guide.md @@ -47,6 +47,9 @@ which is also packed into the package. Running CodeChecker is via its main invocation script, `CodeChecker`: +
+ $ CodeChecker --help (click to expand) + ``` usage: CodeChecker [-h] {analyze,analyzers,check,checkers,cmd,log,parse,server,store,version} @@ -103,7 +106,7 @@ output. CodeChecker check -b "cd ~/myproject && make" ``` - +
## Default configuration @@ -159,6 +162,9 @@ a database. (such as `plist` files), usually previously generated by `CodeChecker analyze` to the database. +
+ $ CodeChecker store --help (click to expand) + ``` usage: CodeChecker store [-h] [-t {plist}] [-n NAME] [--tag TAG] [--description DESCRIPTION] @@ -246,6 +252,7 @@ environment variables: The results can be viewed by connecting to such a server in a Web browser or via 'CodeChecker cmd'. ``` +
For example, if the analysis was run like: @@ -285,6 +292,9 @@ The CodeChecker Viewer server can be browsed by a Web browser by opening the address of it (by default, [`http://localhost:8001`](http://localhost:8001)), or via the `CodeChecker cmd` command-line client. +
+ $ CodeChecker server --help (click to expand) + ``` usage: CodeChecker server [-h] [-w WORKSPACE] [-f CONFIG_DIRECTORY] [--host LISTEN_ADDRESS] [-v PORT] [--not-host-only] @@ -361,6 +371,7 @@ PostgreSQL arguments: --dbname DBNAME, --db-name DBNAME Name of the database to use. (default: config) ``` +
To start a server with default configuration, simply execute @@ -522,6 +533,9 @@ maintenance tasks. Most of the features available in a Web browser opening the analysis result viewer server on its port is available in the `cmd` tool. +
+ $ CodeChecker cmd --help (click to expand) + ``` usage: CodeChecker cmd [-h] {runs,history,results,diff,sum,token,del,update,suppress,products,components,login} @@ -556,6 +570,7 @@ available actions: login Authenticate into CodeChecker servers that require privileges. ``` +
The operations available in `cmd` **always** require a running CodeChecker viewer server (i.e. a server started by `CodeChecker server`), and the @@ -739,6 +754,11 @@ filter arguments: ### Source components (`components`) +
+ + $ CodeChecker cmd components --help (click to expand) + + ``` usage: CodeChecker cmd components [-h] [--url PRODUCT_URL] [--verbose {info,debug,debug_analyzer}] @@ -756,10 +776,16 @@ available actions: add Creates a new source component. del Delete a source component from the server. ``` +
#### New/Edit source component +
+ + $ CodeChecker cmd components add --help (click to expand) + + ``` usage: CodeChecker cmd components add [-h] [--description DESCRIPTION] -i COMPONENT_FILE [--url PRODUCT_URL] @@ -791,6 +817,7 @@ optional arguments: Please see the User guide for more information. ``` +
##### Format of component file @@ -862,6 +889,11 @@ positional arguments: ### List runs (`runs`) +
+ + $ CodeChecker cmd runs --help (click to expand) + + ``` usage: CodeChecker cmd runs [-h] [--url PRODUCT_URL] [-o {plaintext,rows,table,csv,json}] @@ -902,12 +934,18 @@ optional arguments: Sort run data by this column. (default: date) --order {asc,desc} Sort order of the run data. (default: desc) ``` +
### List of run histories (`history`) With this command you can list out the specific storage events which happened during storage processes under multiple run names. +
+ + $ CodeChecker cmd history --help (click to expand) + + ``` usage: CodeChecker cmd history [-h] [-n [RUN_NAME [RUN_NAME ...]]] [--url PRODUCT_URL] @@ -930,12 +968,18 @@ optional arguments: for the last three runs. Use 'CodeChecker cmd runs' to get the available runs. ``` +
### List analysis results' summary (`results`) Prints basic information about analysis results, such as location, checker name, summary. +
+ + $ CodeChecker cmd results --help (click to expand) + + ``` usage: CodeChecker cmd results [-h] [--details] [--uniqueing {on,off}] [--report-hash [REPORT_HASH [REPORT_HASH ...]]] @@ -978,6 +1022,7 @@ optional arguments: --details Get report details for reports such as bug path events, bug report points etc. ``` +
#### Example ``` @@ -1003,6 +1048,11 @@ CodeChecker cmd results -o json --details my_run This mode shows analysis results (in the same format as `results`) does, but from the comparison of two runs. +
+ + $ CodeChecker cmd diff --help (click to expand) + + ``` usage: CodeChecker cmd diff [-h] [-b BASE_RUNS [BASE_RUNS ...]] [-n NEW_RUNS [NEW_RUNS ...]] @@ -1254,6 +1304,7 @@ Compare two runs and show results that exist in both runs and filter results by multiple severity values: CodeChecker cmd diff -b run1 -n run2 --unresolved --severity high medium ``` +
The command can be used in *local* or *remote* compare modes. @@ -1371,6 +1422,10 @@ to the results stored on a remote CodeChecker server previously ``` ### Show summarised count of results (`sum`) +
+ + $ CodeChecker cmd sum --help (click to expand) + ``` usage: CodeChecker cmd sum [-h] (-n RUN_NAME [RUN_NAME ...] | -a) @@ -1418,6 +1473,7 @@ optional arguments: be appeared only once even if it is found on several paths. ``` +
#### Example ```sh @@ -1432,6 +1488,10 @@ CodeChecker cmd sum --all --severity "high" ``` ### Remove analysis runs (`del`) +
+ + $ CodeChecker cmd del --help (click to expand) + ``` usage: CodeChecker cmd del [-h] @@ -1475,8 +1535,13 @@ optional arguments: "time" part can be omitted, in which case midnight (00:00:00) is used). ``` +
### Update an analysis run (`update`) +
+ + $ CodeChecker cmd update --help (click to expand) + ``` usage: CodeChecker cmd update [-h] -n NEW_RUN_NAME [--url PRODUCT_URL] @@ -1493,8 +1558,13 @@ optional arguments: -n NEW_RUN_NAME, --name NEW_RUN_NAME Name name of the analysis run. ``` +
### Manage and export/import suppressions (`suppress`) +
+ + $ CodeChecker cmd suppress --help (click to expand) + ``` usage: CodeChecker cmd suppress [-h] [-f] -i SUPPRESS_FILE [--url PRODUCT_URL] @@ -1514,6 +1584,7 @@ optional arguments: Import suppression from the suppress file into the database. ``` +
#### Import suppressions between server and suppress file @@ -1532,6 +1603,10 @@ the database on the server. Please see [Product management](products.md) for details. ### Authenticate to the server (`login`) +
+ + $ CodeChecker cmd login --help (click to expand) + ``` usage: CodeChecker cmd login [-h] [-d] [--url SERVER_URL] @@ -1556,6 +1631,7 @@ common arguments: --verbose {info,debug,debug_analyzer} Set verbosity level. ``` +
If a server [requires privileged access](authentication.md), you must log in before you can access the data on the particular server. Once diff --git a/tools/plist_to_html/README.md b/tools/plist_to_html/README.md index 054fc54053..472889124c 100644 --- a/tools/plist_to_html/README.md +++ b/tools/plist_to_html/README.md @@ -13,7 +13,12 @@ make package ``` ## Usage -```sh +
+ + $ plist-to-html --help (click to expand) + + +``` usage: plist-to-html [-h] -o OUTPUT_DIR [-l LAYOUT_DIR] file/folder [file/folder ...] @@ -32,6 +37,7 @@ optional arguments: Directory which contains dependency HTML, CSS and JavaScript files. (default: plist_to_html/../static) ``` +
## License diff --git a/tools/report-converter/README.md b/tools/report-converter/README.md index 29cc3c74a6..8bc2bedf61 100644 --- a/tools/report-converter/README.md +++ b/tools/report-converter/README.md @@ -37,7 +37,10 @@ make package ``` ## Usage -```sh +
+ $ report-converter --help (click to expand) + +``` usage: report-converter [-h] -o OUTPUT_DIR -t TYPE [--meta [META [META ...]]] [--filename FILENAME] [-c] [-v] file @@ -101,6 +104,7 @@ Supported analyzers: tslint - TSLint, https://palantir.github.io/tslint ubsan - UndefinedBehaviorSanitizer, https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html ``` +
## Sanitizers ### [Undefined Behaviour Sanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html) diff --git a/tools/tu_collector/README.md b/tools/tu_collector/README.md index b88b518856..ecc3832020 100644 --- a/tools/tu_collector/README.md +++ b/tools/tu_collector/README.md @@ -15,7 +15,12 @@ make package ``` ## Usage -```sh +
+ + $ tu_collector --help (click to expand) + + +``` usage: tu_collector [-h] (-b COMMAND | -l LOGFILE) [-f FILTER] (-z ZIP | -d) [-v] @@ -57,6 +62,7 @@ output arguments: option. The result will not contain header files, even if those are dependents as well. ``` +
## Get source files which include a specific header file Header files can not be analyzed without a C/C++ file. If you change a header