update main index.rst

Author: iplitharas

Makefile

@@ -30,7 +30,7 @@ docs: build-api-docs build-docs  ## Build and server the docs locally
 	cd docs && python -m http.server 8083 --directory _build/html
 
 build-api-docs: ## Build api docs
-	sphinx-apidoc --output-dir docs src src/examples/*.py  --separate
+	sphinx-apidoc --output-dir docs src  src/examples/*.py  --separate
 
 build-docs: ## Build docs
 	sphinx-build docs docs/_build/html

docs/index.rst

@@ -3,18 +3,170 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to pycompile's documentation!
+Welcome to pycompile's docs!
 =====================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
+   CLI
 
-
-Indices and tables
+Contents
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
+
+
+
+CLI
+==================
+1. `compile <#compile>`__
+2. `benchmark <#benchmark>`__
+3. `dry run <#dry-run>`__
+
+
+=================
+compile
+=================
+
++-------------------+--------------------------------------------------+
+| Syntax            | Description                                      |
++===================+==================================================+
+| ``--              | by default it excludes any ``test`` and          |
+| input-path PATH`` | ``__init__.py`` files                            |
++-------------------+--------------------------------------------------+
+| `                 | Deletes the sources files.                       |
+| `--clean-source`` |                                                  |
++-------------------+--------------------------------------------------+
+| ``--keep-builds`` | Keeps the temp build files.                      |
++-------------------+--------------------------------------------------+
+| ``--cl            | Deletes the shared objects (``.so``) files.      |
+| ean-executables`` |                                                  |
++-------------------+--------------------------------------------------+
+| ``--engine``      | Can be ``cython`` or ``nuitka``.                 |
++-------------------+--------------------------------------------------+
+| ``--exc           | Glob file patterns for excluding specific files. |
+| lude-glob-paths`` |                                                  |
++-------------------+--------------------------------------------------+
+| ``--verbose``     | Increase log messages.                           |
++-------------------+--------------------------------------------------+
+
+.. code:: bash
+
+   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:
+
+.. code:: bash
+
+   pycompile -i input_path --engine cython
+
+which by default, deletes any temp build files and keeps the source
+files.
+
+.. code:: bash
+
+   pycompile -i input_path --engine nuitka
+
+
+
+
+After the compilation the ``input`` dir will have the following
+structure.
+
+.. code:: text
+
+   examples
+       ├── fib.py.py
+       ├── fib.cpython-310-darwin.so
+       ├── test_fib.py
+
+
+
+Benchmark
+~~~~~~~~~
+
++-----------------------+----------------------------------------------+
+| Syntax                | Description                                  |
++=======================+==============================================+
+| ``--input-path PATH`` | by default it excludes any ``test`` and      |
+|                       | ``__init__.py`` files                        |
++-----------------------+----------------------------------------------+
+| ``--engine``          | Can be ``cython``, ``nuitka``, ``all`` or    |
+|                       | ``none``.                                    |
++-----------------------+----------------------------------------------+
+| ``--type``            | Can be ``memory`` , ``cpy``, or ``both``     |
++-----------------------+----------------------------------------------+
+| ``--verbose``         | Increase log messages.                       |
++-----------------------+----------------------------------------------+
+| ``--profil            | function name pattern for profiling defaults |
+| e_func_pattern TEXT`` | to ``benchmark``                             |
++-----------------------+----------------------------------------------+
+
+For running a benchmark on the ``input-path`` use the following command:
+
+.. code:: 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``
+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``.
+
+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``.
+
+.. code:: text
+
+    module
+       ├── sample_funcs.py                        # implementation
+       ├── main.py                                # entrypoint with a `main` function
+       ├── test_sample_funcs.py                   # test cases
+
+
+
+
+Dry run
+~~~~~~~
+
++-------------------+--------------------------------------------------+
+| Syntax            | Description                                      |
++===================+==================================================+
+| ``--              | by default it excludes any ``test`` and          |
+| input-path PATH`` | ``__init__.py`` files                            |
++-------------------+--------------------------------------------------+
+| ``--exc           | Glob file patterns for excluding specific files. |
+| lude-glob-paths`` |                                                  |
++-------------------+--------------------------------------------------+
+| ``--verbose``     | Increase log messages.                           |
++-------------------+--------------------------------------------------+
+
+.. code:: bash
+
+   pycompile dry_run -i ./src
+
+
+
+
+
+

src/benchmark.py

@@ -14,7 +14,7 @@
 logger = logging.getLogger(__name__)
 
 
-class Benchmark:  # pylint: disable=invalid-name
+class Benchmark:
     """
     Runs a benchmarks (memory, cpu)  with (``python``, ``Cython``, ``Nuitka``)
     on ``input_path``  files using the:
@@ -98,8 +98,10 @@ def _compile(
     @staticmethod
     def mem_bench(input_path: Path, prof_func_name: str, engine: str) -> None:
         """
-        decorate all the function from the `examples path` marked as `benchmark`
-        with `@profile` decorator from `memory_profiler`
+        decorate all the function(s) from the ``input_path`` where their name match
+        the ``prof_func_name`` pattern,
+        with the ``@profile`` decorator from ``memory_profiler``.
+
         Finally, invoke pytest within.
         """
         logger.info(
@@ -124,8 +126,9 @@ def mem_bench(input_path: Path, prof_func_name: str, engine: str) -> None:
     @staticmethod
     def cpu_bench(input_path: Path, engine: str) -> None:
         """
-        decorate all the test functions from the `examples path`
-        with the `@benchmark_wrapper` decorator
+        decorate all the test functions from the ``input_path``
+        with the ``@benchmark_wrapper`` decorator.
+
         Finally, invoke pytest within.
         """
         logger.info(

src/compiler_handler.py

@@ -14,8 +14,12 @@
 
 class CompilerHandler:
     """
-     CompilerHandler is responsible for compiling all the `.py` files using
-    `Cython` or `Nuitka`
+    CompilerHandler is responsible for compiling all the ``.py`` files using
+    ``Cython`` or ``Nuitka``
+    example usage::
+        compiler_handler = CompilerHandler(files=dir_files,compiler=compiler,
+                            clean_source=True,keep_builds=True)
+        compiler_handler.start()
     """
 
     def __init__(
@@ -65,8 +69,8 @@ def clean_executables(self) -> None:
 
     def start(self) -> None:
         """
-        For each `.py` file runs the compiler command
-        to build the final executable `.so`
+        For each ``.py`` file runs the compiler command
+        to build the final executable ``.so``
         """
         total_iterations = sum(len(files) for files in self.files.values())
         for directory, dir_files in tqdm(

src/file_handler.py

@@ -1,10 +1,10 @@
 """
 FileHandler implementation
-Note:
-`glob patterns`: `**`:   Recursively matches zero or more directories
-                         that fall under the current directory.
-                 `*` :   On Unix, will match everything except slashes.
-                         On Windows, it will avoid matching backslashes as well as slashes.
+glob patterns ::
+    **:   Recursively matches zero or more directories
+          that fall under the current directory.
+    * :   On Unix, will match everything except slashes.
+          On Windows, it will avoid matching backslashes as well as slashes.
 """
 import logging
 from collections import defaultdict
@@ -18,9 +18,10 @@
 
 class FileHandler:
     """
-    FileHandler is responsible for finding all the `.py` files  given
-    any `input_path`.
-    example usage: FileHandler("./my_module).start()
+    FileHandler is responsible for finding all the ``.py`` files within
+    the  ``input_path``.
+    example usage::
+       dir_files = FileHandler("./my_module").start()
     """
 
     def __init__(
@@ -29,9 +30,10 @@ def __init__(
         additional_exclude_patterns: Optional[list[str]] = None,
     ):
         """
-        By default, all the `test` files and any `__init__` files are excluded
-        :param `input_path`: Should be a valid file/directory path.
-        :param `additional_exclude_patterns`: Any optional additional glob patterns.
+        By default, all the ``test`` files and any ``__init__`` files are excluded.
+
+        :param input_path: Should be a valid file/directory path.
+        :param additional_exclude_patterns: Any optional additional glob patterns.
         """
         self.input_path = input_path
         self.exclude_patterns = additional_exclude_patterns or []
@@ -71,8 +73,9 @@ def exclude_patterns(
 
     def start(self) -> dict[str, list[Path]]:
         """
-        For the given `input path` collect all valid `.py` files based on
-        the `exclude_patterns`
+        For the given ``input path`` collect all valid ``.py`` files based on
+        the ``exclude_patterns``
+
         :return: a dictionary for valid files within each directory.
         """
 
@@ -125,10 +128,13 @@ def _collect_files(self) -> Generator[Path, None, None]:
 
     def collect_with_pattern(self, pattern: str) -> Generator[Path, None, None]:
         """
-        Collects all python files from the `input_path` where they mach
-        the `pattern`
+        Collects all python files within the ``input_path`` where they mach
+        the ``pattern``
 
+        :param pattern: str containing glob patters
+        :return: A Generator of file paths.
         """
+
         if not self.input_path.is_dir():
             yield self.input_path
         else:

src/helpers.py

@@ -1,10 +1,5 @@
 """
-implementations for
-`change_dir` context manager,
-`copy_files` context manager,
-`decorate_functions`,
-`run_pytest`,
-and `run_sub_process` helper function.
+pycompile helper functions.
 """
 import ast
 import os
@@ -21,7 +16,11 @@
 
 
 @dataclass(frozen=True)
-class Colors:  # pylint: disable=missing-class-docstring
+class Colors:
+    """
+    pycompile colors
+    """
+
     HEADER = "\033[95m"
     BLUE = "\033[94m"
     CYAN = "\033[96m"