Skip to content

Commit

Permalink
[doc] Using details/summary in md files to show help message
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@csordasmarton
csordasmarton committed Jan 20, 2021
1 parent 3496ecf commit cc807c7
Show file tree
Hide file tree
Showing 9 changed files with 196 additions and 16 deletions.
6 changes: 6 additions & 0 deletions analyzer/tools/merge_clang_extdef_mappings/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,11 @@ make package
```

## Usage
<details>
<summary>
<i>$ <b>merge-clang-extdef-mappings --help</b> (click to expand)</i>
</summary>

```sh
usage: merge-clang-extdef-mappings [-h] -i input -o output

Expand All @@ -40,6 +45,7 @@ Example:
merge-clang-extdef-mappings -i /path/to/fn_map_folder -o
/path/to/externalDefMap.txt
```
</details>

## License

Expand Down
6 changes: 6 additions & 0 deletions analyzer/tools/statistics_collector/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@ make package
```

## Usage
<details>
<summary>
<i>$ <b>post-process-stats --help</b> (click to expand)</i>
</summary>

```sh
usage: post-process-stats [-h] -i folder
[--stats-min-sample-count STATS_MIN_SAMPLE_COUNT]
Expand Down Expand Up @@ -50,6 +55,7 @@ optional arguments:
Example:
post-process-stats -i /path/to/pre_processed_stats /path/to/stats
```
</details>

## License

Expand Down
42 changes: 42 additions & 0 deletions docs/analyzer/user_guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details>
<summary>
<i>$ <b>CodeChecker check --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker check [-h] [-o OUTPUT_DIR] [-t {plist}] [-q]
[--keep-gcc-include-fixed] [--keep-gcc-intrin]
Expand Down Expand Up @@ -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.
```
</details>

# Available CodeChecker analyzer subcommands <a name="available-analyzer-commands"></a>

Expand All @@ -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`.

<details>
<summary>
<i>$ <b>CodeChecker log --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker log [-h] -o LOGFILE -b COMMAND [-q]
[--verbose {info,debug,debug_analyzer}]
Expand Down Expand Up @@ -529,6 +540,7 @@ Environment variables
a 'codechecker.logger.debug' file beside the log
file.
```
</details>

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
Expand Down Expand Up @@ -727,6 +739,11 @@ CodeChecker analyze ../codechecker_myProject_build.log -o my_plists
`CodeChecker analyze` supports a myriad of fine-tuning arguments, explained
below:

<details>
<summary>
<i>$ <b>CodeChecker analyze --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker analyze [-h] [-j JOBS]
[-i SKIPFILE | --file FILE [FILE ...]] -o
Expand Down Expand Up @@ -854,6 +871,7 @@ Environment variables
CC_SEVERITY_MAP_FILE Path of the checker-severity mapping config file.
Default: <package>/config/checker_severity_map.json
```
</details>


### _Skip_ file <a name="skip"></a>
Expand Down Expand Up @@ -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.

<details>
<summary>
<i>$ <b>CodeChecker parse --help</b> (click to expand)</i>
</summary>

```
Usage: CodeChecker parse [-h] [--config CONFIG_FILE] [-t {plist}]
[-e {html,json,codeclimate,gerrit}] [-o OUTPUT_PATH]
Expand Down Expand Up @@ -1566,6 +1589,7 @@ Environment variables
generating gerrit output.
Default: <package>/config/checker_severity_map.json
```
</details>

For example, if the analysis was run like:

Expand All @@ -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.

<details>
<summary>
<i>$ <b>CodeChecker fixit --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker fixit [-h] [-l]
[--checker-name [CHECKER_NAME [CHECKER_NAME...]]]
Expand Down Expand Up @@ -1626,6 +1655,7 @@ optional arguments:
--verbose {info,debug,debug_analyzer}
Set verbosity level.
```
</details>

## `checkers`<a name="checkers"></a>

Expand All @@ -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.

<details>
<summary>
<i>$ <b>CodeChecker checkers --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker checkers [-h] [--analyzers ANALYZER [ANALYZER ...]]
[--details] [--profile {PROFILE/list}]
Expand Down Expand Up @@ -1687,6 +1722,7 @@ Environment variables
CC_PROFILE_MAP_FILE Path of the checker-profile mapping config file.
Default: '<package>/config/checker_profile_map.json'
```
</details>

The list provided by default is formatted for easy machine and human
reading. Use the `--only-` options (`--only-enabled` and `--only-disabled`) to
Expand Down Expand Up @@ -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).

<details>
<summary>
<i>$ <b>CodeChecker analyzers --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker analyzers [-h] [--all] [--details]
[--dump-config {clang-tidy,clangsa}]
Expand Down Expand Up @@ -1755,6 +1796,7 @@ optional arguments:
--verbose {info,debug_analyzer,debug}
Set verbosity level.
```
</details>

A detailed view of the available analyzers is available via `--details`. In the
*detailed view*, version string and install path is also printed.
Expand Down
23 changes: 23 additions & 0 deletions docs/web/authentication.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
<details>
<summary>
<i>$ <b>CodeChecker cmd login --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd login [-h] [-d] [--url SERVER_URL]
[--verbose {info,debug,debug_analyzer}]
Expand All @@ -365,6 +370,7 @@ common arguments:
--verbose {info,debug,debug_analyzer}
Set verbosity level.
```
</details>

The user can log in onto the server by issuing the command `CodeChecker cmd
login <username>`. After receiving an *Authentication successful!* message,
Expand Down Expand Up @@ -457,6 +463,11 @@ Personal tokens can be written instead of the user's password in the
```

## New personal access token <a name="new-personal-access-token"></a>
<details>
<summary>
<i>$ <b>CodeChecker cmd token new --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd token new [-h] [--description DESCRIPTION]
[--url SERVER_URL]
Expand All @@ -470,8 +481,13 @@ optional arguments:
A custom textual description to be shown alongside the
token.
```
</details>

## List personal access tokens <a name="list-personal-access-token"></a>
<details>
<summary>
<i>$ <b>CodeChecker cmd token list --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd token list [-h] [--url SERVER_URL]
Expand All @@ -484,8 +500,14 @@ List the available personal access tokens.
optional arguments:
-h, --help show this help message and exit
```
</details>

## Remove personal access token <a name="remove-personal-access-token"></a>
<details>
<summary>
<i>$ <b>CodeChecker cmd token del --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd token del [-h] [--url SERVER_URL]
[--verbose {info,debug,debug_analyzer}]
Expand All @@ -496,3 +518,4 @@ Removes the specified access token.
positional arguments:
TOKEN Personal access token which will be deleted.
```
</details>
11 changes: 11 additions & 0 deletions docs/web/products.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<details>
<summary>
<i>$ <b>CodeChecker cmd products add --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd products add [-h] [-n DISPLAY_NAME]
[--description DESCRIPTION]
Expand Down Expand Up @@ -166,8 +171,13 @@ PostgreSQL arguments:
--dbname DBNAME, --db-name DBNAME
Name of the database to use. (default: <ENDPOINT>)
```
</details>

## Delete a product (`del`) <a name="delete-a-product"></a>
<details>
<summary>
<i>$ <b>CodeChecker cmd token new --help</b> (click to expand)</i>
</summary>

```
usage: CodeChecker cmd products del [-h] [--url SERVER_URL]
Expand All @@ -186,6 +196,7 @@ positional arguments:
optional arguments:
-h, --help show this help message and exit
```
</details>

# Managing products through the web interface <a name="web-interface"></a>

Expand Down
Loading

0 comments on commit cc807c7

Please sign in to comment.