feat(docs): create docs and update readme

.github/workflows/CI.yml

@@ -20,7 +20,7 @@ concurrency:
   cancel-in-progress: true
 
 permissions:
-  contents: read
+  contents: write
 
 jobs:
   linux:
@@ -123,3 +123,17 @@ jobs:
         with:
           command: upload
           args: --non-interactive --skip-existing *
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force

README.md

@@ -1,36 +1,64 @@
 # complexipy
 
-An extremely fast Python library to calculate the cognitive complexity of
-python files, written in Rust.
+<p align="center">
+    <a href="https://rohaquinlop.github.io/complexipy/"><img src="docs/img/logo-vector.svg" alt="complexipy"></a>
+</p>
 
-## Getting Started
+<p align="center">
+    <em>An extremely fast Python library to calculate the cognitive complexity of python files, written in Rust.</em>
+</p>
 
-### Installation
+<p align="center">
+    <a href="https://sonarcloud.io/summary/new_code?id=rohaquinlop_complexipy" target="_blank">
+        <img src="https://sonarcloud.io/api/project_badges/measure?project=rohaquinlop_complexipy&metric=alert_status" alt="Quality Gate">
+    </a>
+    <a href="https://pypi.org/project/complexipy" target="_blank">
+    <img src="https://img.shields.io/pypi/v/complexipy?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+</p>
 
-**complexipy** is available as
-[`complexipy`](https://pypi.org/project/complexipy/) on PyPI (Python >= 3.11):
+---
+
+**Documentation**: <a href="https://rohaquinlop.github.io/complexipy/" target="_blank">https://rohaquinlop.github.io/complexipy/</a>
+
+**Source Code**: <a href="https://github.com/rohaquinlop/complexipy" target="_blank">https://github.com/rohaquinlop/complexipy</a>
+
+**PyPI**: <a href="https://pypi.org/project/complexipy/" target="_blank">https://pypi.org/project/complexipy/</a>
+
+---
+
+## Requirements
+
+- Python >= 3.11
+- You also need to install `git` in your computer if you want to analyze a git repository.
+
+## Installation
 
 ```bash
 pip install complexipy
 ```
 
-### Usage
+## Usage
 
 To run **complexipy** you can use the following command:
 
-<pre lang="shell">
-<b>complexipy</b> .                         # Use complexipy to analyze the current directory and any subdirectories
-<b>complexipy</b> path/to/directory         # Use complexipy to analyze a specific directory and any subdirectories
-<b>complexipy</b> git_repository_url        # Use complexipy to analyze a git repository
-<b>complexipy</b> path/to/file.py           # Use complexipy to analyze a specific file
-<b>complexipy</b> path/to/file.py -m 20     # Use the -m option to set the maximum congnitive complexity, default is 15
-<b>complexipy</b> path/to/directory -m 0    # Set the maximum cognitive complexity to 0 to disable the exit with error
-<b>complexipy</b> path/to/directory -o      # Use the -o option to output the results to a CSV file, default is False
-</pre>
+```shell
+complexipy .                         # Use complexipy to analyze the current directory and any subdirectories
+complexipy path/to/directory         # Use complexipy to analyze a specific directory and any subdirectories
+complexipy git_repository_url        # Use complexipy to analyze a git repository
+complexipy path/to/file.py           # Use complexipy to analyze a specific file
+complexipy path/to/file.py -m 20     # Use the -m option to set the maximum congnitive complexity, default is 15
+complexipy path/to/directory -m 0    # Set the maximum cognitive complexity to 0 to disable the exit with error
+complexipy path/to/directory -o      # Use the -o option to output the results to a CSV file, default is False
+```
 
 If the cognitive complexity of a file is greater than the maximum cognitive, then
 the return code will be 1 and exit with error, otherwise it will be 0.
 
+## Example
+
+### Analyzing a file
+
 For example, given the following file:
 
 ```python
@@ -50,26 +78,29 @@ def b_decorator(a, b):
 The cognitive complexity of the file is 1, and the output of the command
 `complexipy path/to/file.py` will be:
 
-```bash
-$ complexipy path/to/file.py
-────────────────── complexipy 0.2.0 🐙 ───────────────────
+```txt
+─────────────────────── complexipy 0.2.0 🐙 ───────────────────────
 - Finished analysis in test_decorator.py
-───────────────── Analysis completed! 🎉 ─────────────────
-Results saved to /Users/rhafid/complexipy/complexipy.csv
+──────────────────── 🎉 Analysis completed!🎉 ─────────────────────
                        Summary
 ┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
 ┃ Path              ┃ File              ┃ Complexity ┃
 ┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
 │ test_decorator.py │ test_decorator.py │ 1          │
 └───────────────────┴───────────────────┴────────────┘
+🧠 Total Cognitive Complexity in ./tests/test_decorator.py: 1
 1 files analyzed in 0.0005 seconds
 ```
 
+#### Output to a CSV file
+
 If you want to output the results to a CSV file, you can use the `-o` option,
 this is really useful if you want to integrate **complexipy** with other tools,
 for example, a CI/CD pipeline. You will get the output in the console and will
 create a CSV file with the results of the analysis.
 
+The filename will be `complexipy.csv` and will be saved in the current directory.
+
 ```bash
 $ complexipy path/to/file.py -o
 ```
@@ -81,6 +112,31 @@ Path,File Name,Cognitive Complexity
 test_decorator.py,test_decorator.py,1
 ```
 
+### Analyzing a directory
+
+You can also analyze a directory, for example:
+
+```bash
+$ complexipy .
+```
+
+And **complexipy** will analyze all the files in the current directory and any
+subdirectories.
+
+### Analyzing a git repository
+
+You can also analyze a git repository, for example:
+
+```bash
+$ complexipy https://github.com/rohaquinlop/complexipy
+```
+
+And to generate the output to a CSV file:
+
+```bash
+$ complexipy https://github.com/rohaquinlop/complexipy -o
+```
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file

docs/index.md

@@ -0,0 +1,152 @@
+# complexipy
+
+<p align="center">
+    <a href="https://rohaquinlop.github.io/complexipy/"><img src="img/logo-vector.svg" alt="complexipy"></a>
+</p>
+
+<p align="center">
+    <em>An extremely fast Python library to calculate the cognitive complexity of python files, written in Rust.</em>
+</p>
+
+<p align="center">
+    <a href="https://sonarcloud.io/summary/new_code?id=rohaquinlop_complexipy" target="_blank">
+        <img src="https://sonarcloud.io/api/project_badges/measure?project=rohaquinlop_complexipy&metric=alert_status" alt="Quality Gate">
+    </a>
+    <a href="https://pypi.org/project/complexipy" target="_blank">
+    <img src="https://img.shields.io/pypi/v/complexipy?color=%2334D058&label=pypi%20package" alt="Package version">
+</a>
+</p>
+
+---
+
+**Documentation**: <a href="https://rohaquinlop.github.io/complexipy/" target="_blank">https://rohaquinlop.github.io/complexipy/</a>
+
+**Source Code**: <a href="https://github.com/rohaquinlop/complexipy" target="_blank">https://github.com/rohaquinlop/complexipy</a>
+
+**PyPI**: <a href="https://pypi.org/project/complexipy/" target="_blank">https://pypi.org/project/complexipy/</a>
+
+---
+
+## Requirements
+
+- Python >= 3.11
+- You also need to install `git` in your computer if you want to analyze a git repository.
+
+## Installation
+
+```bash
+pip install complexipy
+```
+
+## Usage
+
+To run **complexipy** you can use the following command:
+
+```shell
+complexipy .                         # Use complexipy to analyze the current directory and any subdirectories
+complexipy path/to/directory         # Use complexipy to analyze a specific directory and any subdirectories
+complexipy git_repository_url        # Use complexipy to analyze a git repository
+complexipy path/to/file.py           # Use complexipy to analyze a specific file
+complexipy path/to/file.py -m 20     # Use the -m option to set the maximum congnitive complexity, default is 15
+complexipy path/to/directory -m 0    # Set the maximum cognitive complexity to 0 to disable the exit with error
+complexipy path/to/directory -o      # Use the -o option to output the results to a CSV file, default is False
+```
+
+If the cognitive complexity of a file is greater than the maximum cognitive, then
+the return code will be 1 and exit with error, otherwise it will be 0.
+
+## Example
+
+### Analyzing a file
+
+For example, given the following file:
+
+```python
+def a_decorator(a, b):
+    def inner(func):
+        return func
+    return inner
+
+def b_decorator(a, b):
+    def inner(func):
+        if func:
+            return None
+        return func
+    return inner
+```
+
+The cognitive complexity of the file is 1, and the output of the command
+`complexipy path/to/file.py` will be:
+
+```txt
+─────────────────────── complexipy 0.2.0 🐙 ───────────────────────
+- Finished analysis in test_decorator.py
+──────────────────── 🎉 Analysis completed!🎉 ─────────────────────
+                       Summary
+┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Path              ┃ File              ┃ Complexity ┃
+┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ test_decorator.py │ test_decorator.py │ 1          │
+└───────────────────┴───────────────────┴────────────┘
+🧠 Total Cognitive Complexity in ./tests/test_decorator.py: 1
+1 files analyzed in 0.0005 seconds
+```
+
+#### Output to a CSV file
+
+If you want to output the results to a CSV file, you can use the `-o` option,
+this is really useful if you want to integrate **complexipy** with other tools,
+for example, a CI/CD pipeline. You will get the output in the console and will
+create a CSV file with the results of the analysis.
+
+The filename will be `complexipy.csv` and will be saved in the current directory.
+
+```bash
+$ complexipy path/to/file.py -o
+```
+
+The output will be:
+
+```csv
+Path,File Name,Cognitive Complexity
+test_decorator.py,test_decorator.py,1
+```
+
+### Analyzing a directory
+
+You can also analyze a directory, for example:
+
+```bash
+$ complexipy .
+```
+
+And **complexipy** will analyze all the files in the current directory and any
+subdirectories.
+
+### Analyzing a git repository
+
+You can also analyze a git repository, for example:
+
+```bash
+$ complexipy https://github.com/rohaquinlop/complexipy
+```
+
+And to generate the output to a CSV file:
+
+```bash
+$ complexipy https://github.com/rohaquinlop/complexipy -o
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+for details.
+
+## Acknowledgments
+
+- This project is inspired by the sonar way to calculate the cognitive
+complexity.
+
+## References
+
+- [Cognitive Complexity](https://www.sonarsource.com/resources/cognitive-complexity/)

mkdocs.yml

@@ -0,0 +1,51 @@
+site_name: complexipy
+site_description: An extremely fast Python library to calculate the cognitive complexity of python files, written in Rust.
+site_url: https://rohaquinlop.github.io/complexipy/
+repo_name: rohaquinlop/complexipy
+repo_url: https://github.com/rohaquinlop/complexipy
+edit_uri: ""
+
+theme:
+  name: material
+  features:
+    - navigation.top
+    - search.suggest
+    - search.highlight
+    - content.tabs.link
+    - content.code.annotation
+    - content.code.copy
+  language: en
+  palette:
+    primary: purple
+  icon:
+    repo: fontawesome/brands/github-alt
+  logo: img/icon.svg
+  favicon: img/favicon.svg
+
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/rohaquinlop
+    - icon: fontawesome/brands/linkedin
+      link: https://www.linkedin.com/in/robin-hafid-quintero-lopez/
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - admonition
+  - pymdownx.superfences
+  - pymdownx.arithmatex:
+      generic: true
+  - pymdownx.details
+  - footnotes
+  - pymdownx.mark
+  - attr_list
+  - pymdownx.extra
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+copyright:
+  Copyright &copy; 2021 <a href="https://github.com/rohaquinlop" target="_blank" rel="noopener">Robin Hafid Quintero Lopez</a>