Merge pull request #548 from yukinarit/update-se-docs

Update documentation of from_dict/to_dict

README.md

@@ -21,7 +21,9 @@
 
 ## Overview
 
-Declare a class with pyserde's `@serde` decorator.
+`pyserde` is a simple yet powerful serialization library on top of [dataclasses](https://docs.python.org/3/library/dataclasses.html). It allows you to convert Python objects to and from JSON, YAML, and other formats easily and efficiently.
+
+Declare your class with `@serde` decorator and annotate fields using [PEP484](https://peps.python.org/pep-0484/) as below.
 
 ```python
 @serde
@@ -45,6 +47,12 @@ You can deserialize JSON into `Foo` object.
 Foo(i=10, s='foo', f=100.0, b=True)
 ```
 
+That's it!  If you're interested in pyserde, please check our documentation!
+Happy coding with pyserde! 🚀
+* [Getting started](https://yukinarit.github.io/pyserde/guide/en/getting-started.html)
+* [API Reference](https://yukinarit.github.io/pyserde/api/serde.html)
+* [Examples](https://github.com/yukinarit/pyserde/tree/main/examples)
+
 ## Features
 
 - Supported data formats

docs/en/data-formats.md

@@ -1,6 +1,6 @@
 # Data Formats
 
-Currently `dict`, `tuple`, `JSON`, `Yaml`, `Toml`, `MsgPack` and `Pickle` are supported. Each Serialize/Deserialize API can take additional keyword arguments. Keyword arguements are forwared to the packages which is used by pyserde to encode data internally.
+pyserde supports several data formats for serialization and deserialization, including `dict`, `tuple`, `JSON`, `YAML`, `TOML`, `MsgPack`, and `Pickle`. Each API can take additional keyword arguments, which are forwarded to the underlying packages used by pyserde.
 
 e.g. If you want to preserve the field order in YAML, you can pass `sort_key=True` in `serde.yaml.to_yaml`
 

docs/en/getting-started.md

@@ -109,5 +109,5 @@ print(from_json(Foo, s))
 
 That's it! pyserde offers many more features. If you're interested, please read the rest of the documentation.
 
-> **NOTE:** which type checker should be used?
-> pyserde depends on [PEP681 dataclass_transform](https://peps.python.org/pep-0681/). [mypy](https://github.com/python/mypy) does not fully support dataclass_transform as of Jan. 2024. [pyright](https://github.com/microsoft/pyright) is recommended for codebase using pyserde.
+> 💡 Tip: which type checker should I use?
+> pyserde depends on [PEP681 dataclass_transform](https://peps.python.org/pep-0681/). [mypy](https://github.com/python/mypy) does not fully support dataclass_transform as of Jan. 2024. My personal recommendation is [pyright](https://github.com/microsoft/pyright).

serde/se.py

@@ -436,9 +436,22 @@ def to_dict(
     convert_sets: Optional[bool] = None,
 ) -> dict[Any, Any]:
     """
-    Serialize object into dictionary.
-
-    >>> @serialize
+    Serialize object into python dictionary. This function ensures that the dataclass's fields are
+    accurately represented as key-value pairs in the resulting dictionary.
+
+    * `o`: Any pyserde object that you want to convert to `dict`
+    * `c`: Optional class argument
+    * `reuse_instances`: pyserde will pass instances (e.g. Path, datetime) directly to serializer
+    instead of converting them to serializable representation e.g. string. This behaviour allows
+    to delegate serializtation to underlying data format packages e.g. `pyyaml` and potentially
+    improve performance.
+    * `convert_sets`: This option controls how sets are handled during serialization and
+    deserialization. When `convert_sets` is set to True, pyserde will convert sets to lists during
+    serialization and back to sets during deserialization. This is useful for data formats that
+    do not natively support sets.
+
+    >>> from serde import serde
+    >>> @serde
     ... class Foo:
     ...     i: int
     ...     s: str = 'foo'
@@ -448,7 +461,8 @@ def to_dict(
     >>> to_dict(Foo(i=10))
     {'i': 10, 's': 'foo', 'f': 100.0, 'b': True}
 
-    You can pass any type supported by pyserde. For example,
+    You can serialize not only pyserde objects but also objects of any supported types. For example,
+    the following example serializes list of pyserde objects into dict.
 
     >>> lst = [Foo(i=10), Foo(i=20)]
     >>> to_dict(lst)