update main readme, add sphnix dependencies for markdown support

Author: iplitharas

Makefile

@@ -43,8 +43,16 @@ build-docs: ## Build docs
 clean:  ## Clean temp dirs
 	rm -rf  .pytest_cache coverage.xml .mypy_cache  .coverage .coverage.* htmlcov
 
+docs: ## Generate docs
+	 sphinx-apidoc src --output-dir docs/source_code/ --maxdepth 1 \
+     &&  rm -rf docs/_build/* \
+ 	 && sphinx-build docs docs/_build/html
+
+docs-live: docs  ## Start a local server to render the docs
+	 python -m http.server 8091 --directory  docs/_build/html
+
 .PHONY: help create-env poetry-install install-hooks check test package-install \
- 		setup-local-dev docs build-api-docs build-docs clean-hooks clean
+ 		setup-local-dev docs build-api-docs build-docs clean-hooks clean docs docs-live
 
 help:
 	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' $(MAKEFILE_LIST)

README.md

@@ -56,7 +56,9 @@ pycompile -i your_python_files --clean-source --engine nuitka
 By default, the [Cython](https://cython.org/) is being used as the default
 compiler. 
 
-For compiling the `examples` use the following command:
+> [!TIP]
+> For compiling the `examples` use the following command
+
 ```bash
 pycompile -i input_path --engine cython 
 ```
@@ -88,26 +90,29 @@ examples
 | --verbose                   | Increase log messages.                                      |
 | --profile_func_pattern TEXT | function name pattern for profiling defaults to `benchmark` |
 
-For running a benchmark on  the `input-path` use the following command:
+For running a benchmark on the `input-path` use the following command:
 ```bash
 pycompile benchmark -i src/examples -vvv
 ```
 which by default will start a `memory` and a `cpu` benchmark, starting with 
 `python` and then with `cython` and `nuitka`
+> [!IMPORTANT]
 > The python package must have a `test_module.py` because both benchmark types are invoked 
 > with `pytest` runs
 
-* For **memory profiling** the script will decorate all the functions in `benchmark.py` 
-  with the `profile` decorator from `memory-profiler`. This is not optimal memory profiling, 
-  because we don't actually `profile` the function itself, instead we profile the `caller` but it's necessary
-  if we want to `profile` also the compiled code.
-  Use the `profile_func_pattern` to specify the function to be profiled in different module for example 
-  if `main` is the entrypoint under `main.py` use `--profile_func_pattern main`.
+> [!NOTE]
+> For **memory profiling** the script will decorate all the functions in `benchmark.py` 
+> with the `profile` decorator from `memory-profiler`. This is not optimal memory profiling, 
+> because we don't actually `profile` the function itself, instead we profile the `caller` but it's necessary
+> if we want to `profile` also the compiled code.
+> Use the `profile_func_pattern` to specify the function to be profiled in different module for example 
+> if `main` is the entrypoint under `main.py` use `--profile_func_pattern main`.
 
 Hence, the following structure are required for the `benchmark` subcommand.
 
-* For **cpu profiling** the same approached is being used, but instead of decorating the `calling functions` 
-  it `decorates` the test cases with the `benchmark` from `pytest-benchmark`.
+> [NOTE]
+> For **cpu profiling** the same approached is being used, but instead of decorating the `calling functions` 
+> it `decorates` the test cases with the `benchmark` from `pytest-benchmark`.
 
 
 ```text
@@ -132,36 +137,7 @@ Line #    Mem usage    Increment  Occurrences   Line Contents
 ```text
 46.03s call     test_examples.py::test_examples
 ```
-**Memory benchmark** using [cython](https://cython.org/)
-```text
-Line #    Mem usage    Increment  Occurrences   Line Contents
-=============================================================
-     7     66.5 MiB     66.5 MiB           1   @profile
-     8                                         def samples_benchmark():
-     9    103.7 MiB     37.3 MiB           1       sum_of_squares()
-    10    102.9 MiB     -0.8 MiB           1       harmonic_mean()
-    11    102.9 MiB      0.0 MiB           1       fibonacci(30)
-    12    104.9 MiB      2.0 MiB           1       sum_numbers()
-    13     65.6 MiB    -39.3 MiB           1       sum_strings()
-```
-```text
-4.33s call     test_examples.py::test_examples
-```
-**Memory benchmark** using [nuitka](https://nuitka.net/index.html)
-```text
-Line #    Mem usage    Increment  Occurrences   Line Contents
-=============================================================
-     7     71.6 MiB     71.6 MiB           1   @profile
-     8                                         def samples_benchmark():
-     9    148.8 MiB     77.1 MiB           1       sum_of_squares()
-    10    186.5 MiB     37.7 MiB           1       harmonic_mean()
-    11    186.5 MiB      0.0 MiB           1       fibonacci(30)
-    12    225.1 MiB     38.6 MiB           1       sum_numbers()
-    13    225.1 MiB      0.0 MiB           1       sum_strings()
-```
-```text
-3.45s call     test_examples.py::test_examples
-```
+
 
 **CPU benchmark** using:`3.10.9 (main, Feb  2 2023, 12:59:36) [Clang 14.0.0 (clang-1400.0.29.202)]`
 ```text
@@ -178,39 +154,8 @@ Legend:
 29.40s call     test_examples.py::test_examples
 ```
 
-**CPU benchmark** using [cython](https://cython.org/)
-```text
-Name (time in s)        Min     Max    Mean  StdDev  Median     IQR  Outliers     OPS  Rounds  Iterations
----------------------------------------------------------------------------------------------------------
-test_examples        4.4198  4.6645  4.4945  0.1048  4.4340  0.1376       1;0  0.2225       5           1
----------------------------------------------------------------------------------------------------------
-
-Legend:
-  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
-  OPS: Operations Per Second, computed as 1 / Mean
-===================================================================================================================
-31.80s call     test_examples.py::test_examples
-```
-
-**CPU benchmark** using [nuitka](https://nuitka.net/index.html)
-```text
-------------------------------------------- benchmark: 1 tests ------------------------------------------
-Name (time in s)        Min     Max    Mean  StdDev  Median     IQR  Outliers     OPS  Rounds  Iterations
----------------------------------------------------------------------------------------------------------
-test_examples        3.2931  3.5091  3.4278  0.0972  3.4875  0.1571       1;0  0.2917       5           1
----------------------------------------------------------------------------------------------------------
-
-Legend:
-  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
-  OPS: Operations Per Second, computed as 1 / Mean
-===================================================================================================================
-24.02s call     test_examples.py::test_examples
-```
-
-
 ![benchmark_cython_python.gif](data/benchmark_cython_python.gif)
 
-
 ### Dry run 
 
 | Syntax               | Description                                               |