docs(readme): add documentation about filename templates and call filtering

Author: lucsorel

README.md

@@ -73,6 +73,139 @@ poetry add pydoctrace
 pipenv install pydoctrace
 ```
 
+## Usage
+
+Import a decorator and apply it to the functions whom execution you want to trace:
+
+```python
+# in my_package/my_module.py
+from pydoctrace.doctrace import trace_to_component_puml, trace_to_sequence_puml
+
+def main(parameter):
+    validate(parameter)
+    do_something(parameter)
+
+@trace_to_component_puml
+def validate(parameter):
+    validate_is_not_none(parameter)
+    validate_is_in_database(parameter)
+
+@trace_to_sequence_puml
+def do_something(parameter):
+    stuff = load_stuff(parameter)
+    save_work(process_job(stuff))
+```
+
+Executing `main()` will create 2 diagram files in the current working directory:
+
+* `validate-component.puml`: a PlantUML **component** diagram showing the interactions between `validate()` as the start, and `validate_is_not_none()` and `validate_is_in_database()` (and all their inner function calls, if any)
+* `do_something-sequence.puml`: a PlantUML **sequence** diagram showing the interactions between `do_something()` as the start, and `load_stuff()`, `process_job()` and `save_work()` (and all their inner function calls, if any)
+
+You can then view these files either:
+
+* using an extension for your IDE: `jebbs.plantuml` for Codium / vsCode, `7017-plantuml-integration` for PyCharm
+* online at www.plantuml.com/plantuml/uml/
+
+### Customize the filename
+
+The `export_file_path_tpl` attribute of the decorators allows you to define another file path and name:
+
+```python
+# in my_package/my_module.py
+from pydoctrace.doctrace import trace_to_component_puml, trace_to_sequence_puml
+
+# will create a 'validate-component.puml' file in the 'doc/my_package-my_module' folder
+# (pydoctrace will create the subdirectories if necessary)
+@trace_to_component_puml(
+    export_file_path_tpl='doc/my_package-my_module/validate-component.puml'
+)
+def validate(parameter):
+    ...
+
+# will create a 'my_package.my_module/do_something-2024-02-27_19.16.09_473-sequence.puml' file
+@trace_to_sequence_puml(
+    export_file_path_tpl='${function_module}/${function_name}-${datetime_millis}-sequence.puml'
+)
+def do_something(parameter):
+    ...
+```
+
+As you can see, you can use the following template tags in the file name:
+
+* `${function_module}`: which resolves to `do_something.__module__`, `'my_package.my_module'` in the example
+* `${function_name}`: which resolves to `do_something.__name__`, `'do_something'` in the example
+* `${datetime_millis}`: the datetime in ISO-ish format compatible with filenames (Windows does not support `':'` in filenames).
+If the traced function is called several times during the execution, including `${datetime_millis}` in the filename template will generate different files that won't overwrite themselves
+
+### Filter what is traced
+
+To keep the generated diagrams useful and legible, you probably want to exclude some calls from the tracing (such as calls to `print(...)` or `json.load(...)`).
+`pydoctrace` comes with ready-to-use [presets](pydoctrace/callfilter/presets.py) that you can combine to filter out some calls you do not want to document:
+
+* `EXCLUDE_BUILTINS_PRESET`: prevents from tracing calls to [built-in functions](https://docs.python.org/3/library/functions.html) (`print`, `len`, `all`, `any`, etc.)
+* `EXCLUDE_STDLIB_PRESET`: prevents from tracing calls to all [the standard library modules](https://docs.python.org/3/library/index.html) (`csv`, `json`, `dataclass`, etc.)
+* `EXCLUDE_TESTS_PRESET`: prevents from tracing calls to functions belonging to the `tests`, `_pytest`, `pytest`, `unittest`, `doctest` modules.
+This one is particularly useful when you want to generate some documentation from an automated tests
+* `EXCLUDE_DEPTH_BELOW_5_PRESET`: prevents from tracing any calls that involve a call stack of more than five levels after the traced function
+
+By default, `EXCLUDE_STDLIB_PRESET` and `EXCLUDE_TESTS_PRESET` are activated.
+Specify something else at the decorator level to change the call filtering.
+
+```python
+from pydoctrace.doctrace import trace_to_component_puml
+from pydoctrace.callfilter.presets import (
+    EXCLUDE_BUILTINS_PRESET,
+    EXCLUDE_CALL_DEPTH_PRESET_FACTORY,
+    EXCLUDE_DEPTH_BELOW_5_PRESET,
+    EXCLUDE_STDLIB_PRESET,
+    EXCLUDE_TESTS_PRESET,
+    TRACE_ALL_PRESET,
+)
+
+# an empty presets list traces everything
+@trace_to_component_puml(filter_presets=[])
+def validate(parameter):
+    ...
+# or you can be explicit
+from pydoctrace.callfilter.presets import TRACE_ALL_PRESET
+@trace_to_component_puml(filter_presets=[TRACE_ALL_PRESET])
+def validate(parameter):
+    ...
+
+# filter at a custom callstack level
+from pydoctrace.callfilter.presets import EXCLUDE_CALL_DEPTH_PRESET_FACTORY
+ABOVE_3_PRESET = EXCLUDE_CALL_DEPTH_PRESET_FACTORY(3)
+@trace_to_component_puml(filter_presets=[ABOVE_3_PRESET])
+def call():
+    call_1()
+
+def call_1():
+    call_2()
+
+def call_2():
+    call_3()
+
+def call_3(): # will not be traced in the diagram
+    ...
+
+# documents the behavior of do_something without the noise of
+# the test framework nor the standard libray
+from my_package.my_module import do_something
+from pydoctrace.callfilter.presets import EXCLUDE_STDLIB_PRESET, EXCLUDE_TESTS_PRESET
+@trace_to_component_puml(filter_presets=[EXCLUDE_STDLIB_PRESET, EXCLUDE_TESTS_PRESET])
+def test_do_something():
+    assert do_something('param') is not None
+
+# for test-generated documentation, you can also use the decorator programmatically
+def test_do_something():
+    traceable_do_something = trace_to_component_puml(
+        export_file_path_tpl='doc/${function_module}/${function_name}-component.puml',
+        filter_presets=[EXCLUDE_STDLIB_PRESET, EXCLUDE_TESTS_PRESET, ABOVE_3_PRESET]
+    )(do_something)
+
+    assert traceable_do_something('param') is not None
+```
+
 ## Purposes and mechanisms
 
 The purpose of `pydoctrace` is to document the execution of some code to illustrate the behavior and the structure of the code base.