Pretty up the home index for the docs

* Make use of grids to display information in an easier-to-read format * Convert man page rst into markdown and provide link to it * The grid links to the getting started, CLI reference, rules, and license Signed-off-by: Eric Brown <[email protected]>
securesauce · Jul 19, 2024 · 3bfd4de · 3bfd4de
1 parent 500603c
commit 3bfd4de
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 32 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,4 +1,4 @@
-exclude: ^(docs|tests)
+exclude: ^(docs|tests|mkdocs.yml)
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v4.4.0

diff --git a/docs/index.md b/docs/index.md
@@ -4,7 +4,39 @@ Precli is the core library for the GitHub App Precaution. It also serves as
 a command line interface. Precli is a SAST that analyzes code for security
 vulnerabilities.
 
-## License
 
-`precli` is provided under the terms and conditions of the
-[Business Source License 1.1](https://github.com/securesauce/precli/blob/main/LICENSE)
+<div class="grid cards" markdown>
+
+-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__
+
+    ---
+
+    Install `precli` with `pip` and get up and running in minutes
+
+    [:octicons-arrow-right-24: Getting started](getting-started)
+
+-   :material-console:{ .lg .middle } __CLI Reference__
+
+    ---
+
+    Guide on usage of the command line
+
+    [:octicons-arrow-right-24: CLI Reference](man/precli)
+
+-   :material-ruler:{ .lg .middle } __Explore Rules__
+
+    ---
+
+    Explore the various rules used in the detection of vulnerabilities
+
+    [:octicons-arrow-right-24: Rules](rules)
+
+-   :material-scale-balance:{ .lg .middle } __Open Source, BSL__
+
+    ---
+
+    Precli is licensed under `Business Source License` and available on [GitHub](https://github.com/securesauce/precli)
+
+    [:octicons-arrow-right-24: License](https://github.com/securesauce/precli/blob/main/LICENSE)
+
+</div>
diff --git a/docs/man/precli.rst → docs/man/precli.md b/docs/man/precli.rst → docs/man/precli.md
@@ -1,26 +1,23 @@
-======
-precli
-======
+# precli
 
-SYNOPSIS
-========
+## SYNOPSIS
 
+```
 precli [-h] [-d] [-r] [--enable ENABLE] [--disable DISABLE] [--json] [--plain]
        [--markdown] [--gist] [-o OUTPUT] [--no-color] [-q] [--version]
        [targets ...]
+```
 
+## DESCRIPTION
 
-DESCRIPTION
-===========
-
-``precli`` is a tool designed to find security issues in code. It finds issues
+`precli` is a tool designed to find security issues in code. It finds issues
 such as injection, weak hashes, cleartext transmission of data, timing
 attacks, weak encryption, deserialization of untrusted data, improper
 certificate validation, and more.
 
-OPTIONS
-=======
+## OPTIONS
 
+```
   -h, --help            show this help message and exit
   -d, --debug           turn on debug mode
   -r, --recursive       find and process files in subdirectories
@@ -35,24 +32,24 @@ OPTIONS
   --no-color            do not display color in output
   -q, --quiet           quiet mode, display less output
   --version             show program's version number and exit
+```
 
-FILES
-=====
+## FILES
 
 .preignore
   file that specifies which files and directories can be ignored
 
-ENVIRONMENT VARIABLES
-=====================
+## ENVIRONMENT VARIABLES
 
 DEBUG
+
   Set to any value to enabling debug logging.
 
 GITHUB_TOKEN
-  Set to your GitHub token. This is required to use the ``--gist`` argument.
 
-EXAMPLES
-========
+  Set to your GitHub token. This is required to use the `--gist` argument.
+
+## EXAMPLES
 
 Example usage across a code tree::
 
@@ -63,12 +60,10 @@ run Precli with standard input::
 
     cat examples/imports.py | precli -
 
-REPORTING BUGS
-==============
+## REPORTING BUGS
 
-Report issues at the following link: https://github.com/securesauce/precli/issues
+Report issues at the following link: [https://github.com/securesauce/precli/issues](https://github.com/securesauce/precli/issues)
 
-SEE ALSO
-========
+## SEE ALSO
 
-pylint(1)
+`pylint(1)`
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -17,10 +17,9 @@ plugins:
   - search
 
 nav:
-  - Home:
-    - index.md
-  - 'User Guide':
-    - getting-started.md
+  - Home: index.md
+  - getting-started.md
+  - 'CLI Reference': man/precli.md
   - Rules:
     - Rules: rules.md
 
@@ -34,3 +33,8 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
       alternate_style: true
+  - attr_list
+  - md_in_html
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg