Update docs for #560

yukinarit · Jun 20, 2024 · 2fad35b · 2fad35b
1 parent 0608894
commit 2fad35b
Show file tree

Hide file tree

Showing 37 changed files with 4,868 additions and 2,597 deletions.
diff --git a/api/search.js b/api/search.js
diff --git a/api/serde.html b/api/serde.html
diff --git a/api/serde/compat.html b/api/serde/compat.html
diff --git a/api/serde/core.html b/api/serde/core.html
diff --git a/api/serde/se.html b/api/serde/se.html
diff --git a/guide/en/book.toml b/guide/en/book.toml
@@ -7,4 +7,4 @@ title = "pyserde documentation"
 
 [output.html]
 git-repository-url = "https://github.com/yukinarit/pyserde"
-edit-url-template = "https://github.com/yukinarit/pyserde/edit/main/en/{path}"
+edit-url-template = "https://github.com/yukinarit/pyserde/edit/main/docs/en/{path}"
diff --git a/guide/en/class-attributes.html b/guide/en/class-attributes.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//class-attributes.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//class-attributes.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 
@@ -294,7 +294,7 @@ <h3 id="serializer--deserializer"><a class="header" href="#serializer--deseriali
 </code></pre>
 <p>See <a href="https://github.com/yukinarit/pyserde/blob/main/examples/custom_legacy_class_serializer.py">examples/custom_legacy_class_serializer.py</a> for complete example.</p>
 <h3 id="type_check"><a class="header" href="#type_check"><strong><code>type_check</code></strong></a></h3>
-<p>New in v0.9.0. See <a href="#type-check.md">Type Check</a>.</p>
+<p>New in v0.9.0. See <a href="type-check.html">Type Check</a>.</p>
 <h3 id="serialize_class_var"><a class="header" href="#serialize_class_var"><strong><code>serialize_class_var</code></strong></a></h3>
 <p>New in v0.9.8. Since <code>dataclasses.fields</code> doesn't include a class variable <sup class="footnote-reference"><a href="#1">1</a></sup>, pyserde doesn't serialize class variable as default. This option allows a field of <code>typing.ClassVar</code> to be serialized.</p>
 <pre><code class="language-python">@serde(serialize_class_var=True)
@@ -303,7 +303,7 @@ <h3 id="serialize_class_var"><a class="header" href="#serialize_class_var"><stro
 </code></pre>
 <p>See <a href="https://github.com/yukinarit/pyserde/blob/main/examples/class_var.py">examples/class_var.py</a> for complete example.</p>
 <div class="footnote-definition" id="1"><sup class="footnote-definition-label">1</sup>
-<p>https://docs.python.org/3/library/dataclasses.html#dataclasses.fields</p>
+<p><a href="https://docs.python.org/3/library/dataclasses.html#dataclasses.fields">dataclasses.fields</a></p>
 </div>
 
                     </main>

diff --git a/guide/en/data-formats.html b/guide/en/data-formats.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//data-formats.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//data-formats.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 
@@ -180,7 +180,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                 <div id="content" class="content">
                     <main>
                         <h1 id="data-formats"><a class="header" href="#data-formats">Data Formats</a></h1>
-<p>Currently <code>dict</code>, <code>tuple</code>, <code>JSON</code>, <code>Yaml</code>, <code>Toml</code>, <code>MsgPack</code> and <code>Pickle</code> 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.</p>
+<p>pyserde supports several data formats for serialization and deserialization, including <code>dict</code>, <code>tuple</code>, <code>JSON</code>, <code>YAML</code>, <code>TOML</code>, <code>MsgPack</code>, and <code>Pickle</code>. Each API can take additional keyword arguments, which are forwarded to the underlying packages used by pyserde.</p>
 <p>e.g. If you want to preserve the field order in YAML, you can pass <code>sort_key=True</code> in <code>serde.yaml.to_yaml</code></p>
 <pre><code class="language-python">serde.yaml.to_yaml(foo, sort_key=True)
 </code></pre>

diff --git a/guide/en/decorators.html b/guide/en/decorators.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//decorators.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//decorators.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 

diff --git a/guide/en/extension.html b/guide/en/extension.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//extension.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//extension.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 

diff --git a/guide/en/faq.html b/guide/en/faq.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//faq.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//faq.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 

diff --git a/guide/en/field-attributes.html b/guide/en/field-attributes.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//field-attributes.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//field-attributes.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 

diff --git a/guide/en/getting-started.html b/guide/en/getting-started.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//getting-started.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//getting-started.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 
@@ -187,7 +187,7 @@ <h2 id="installation"><a class="header" href="#installation">Installation</a></h
 <p>If you're using poetry, run this command.</p>
 <pre><code>poetry add pyserde
 </code></pre>
-<p>Additional data formats besides JSON and Pickle need additional dependencies installed. Install <code>msgpack</code>, <code>toml</code>, or <code>yaml</code> extras to work with the appropriate data formats; you can skip formats that you don't plan to use. For example, if you want to use Toml and YAML:</p>
+<p>Additional data formats besides JSON and Pickle need additional dependencies installed. Install <code>msgpack</code>, <code>toml</code> or <code>yaml</code> extras to work with the appropriate data formats; you can skip formats that you don't plan to use. For example, if you want to use Toml and YAML:</p>
 <pre><code>pip install "pyserde[toml,yaml]"
 </code></pre>
 <p>With poetry</p>
@@ -201,7 +201,7 @@ <h2 id="installation"><a class="header" href="#installation">Installation</a></h
 </code></pre>
 <p>Here are the available extras</p>
 <ul>
-<li><code>all</code>: Install <code>msgpack</code>, <code>toml</code>, <code>yaml</code> and <code>numpy</code> extras</li>
+<li><code>all</code>: Install <code>msgpack</code>, <code>toml</code>, <code>yaml</code>, <code>numpy</code>, <code>orjson</code>, and <code>sqlalchemy</code> extras</li>
 <li><code>msgpack</code>: Install <a href="https://github.com/msgpack/msgpack-python">msgpack</a></li>
 <li><code>toml</code>: Install <a href="https://github.com/hukkin/tomli">tomli</a> and <a href="https://github.com/hukkin/tomli-w">tomli-w</a>
 <ul>
@@ -210,6 +210,8 @@ <h2 id="installation"><a class="header" href="#installation">Installation</a></h
 </li>
 <li><code>yaml</code>: Install <a href="https://github.com/yaml/pyyaml">pyyaml</a></li>
 <li><code>numpy</code>: Install <a href="https://github.com/numpy/numpy">numpy</a></li>
+<li><code>orjson</code>: Install <a href="https://github.com/ijl/orjson">orjson</a></li>
+<li><code>sqlalchemy</code>: Install <a href="https://github.com/sqlalchemy/sqlalchemy">sqlalchemy</a></li>
 </ul>
 <h2 id="define-your-first-pyserde-class"><a class="header" href="#define-your-first-pyserde-class">Define your first pyserde class</a></h2>
 <p>Define your class with pyserde's <code>@serde</code> decorators. Be careful that module name is <code>serde</code>, not <code>pyserde</code>. <code>pyserde</code> heavily depends on the standard library's <code>dataclasses</code> module. If you are new to dataclass, I would recommend to read <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses documentation</a> first.</p>
@@ -260,8 +262,8 @@ <h2 id="use-pyserde-class"><a class="header" href="#use-pyserde-class">Use pyser
 </code></pre>
 <p>That's it! pyserde offers many more features. If you're interested, please read the rest of the documentation.</p>
 <blockquote>
-<p><strong>NOTE:</strong> which type checker should be used?
-pyserde depends on <a href="https://peps.python.org/pep-0681/">PEP681 dataclass_transform</a>. <a href="https://github.com/python/mypy">mypy</a> does not fully support dataclass_transform as of Jan. 2024. <a href="https://github.com/microsoft/pyright">pyright</a> is recommended for codebase using pyserde.</p>
+<p>💡 Tip: which type checker should I use?
+pyserde depends on <a href="https://peps.python.org/pep-0681/">PEP681 dataclass_transform</a>. <a href="https://github.com/python/mypy">mypy</a> does not fully support dataclass_transform as of Jan. 2024. My personal recommendation is <a href="https://github.com/microsoft/pyright">pyright</a>.</p>
 </blockquote>
 
                     </main>

diff --git a/guide/en/index.html b/guide/en/index.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//introduction.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//introduction.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 
@@ -180,22 +180,34 @@ <h1 class="menu-title">pyserde documentation</h1>
                 <div id="content" class="content">
                     <main>
                         <h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
-<p><code>pyserde</code> is a simple yet powerful serialization library on top of <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses</a>. Simply adding pyserde's <code>@serde</code> decorator makes your class (de)serializable from/to many data formats.</p>
-<pre><code class="language-python">@serde
+<p><code>pyserde</code> is a simple yet powerful serialization library on top of <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses</a>. It allows you to convert Python objects to and from JSON, YAML, and other formats easily and efficiently.</p>
+<p>Declare your class with <code>@serde</code> decorator and annotate fields using <a href="https://peps.python.org/pep-0484/">PEP484</a> as below.</p>
+<pre><code class="language-python">from serde import serde
+
+@serde
 class Foo:
     i: int
     s: str
     f: float
     b: bool
 </code></pre>
 <p>You can serialize <code>Foo</code> object into JSON.</p>
-<pre><code class="language-python">&gt;&gt;&gt; to_json(Foo(i=10, s='foo', f=100.0, b=True))
+<pre><code class="language-python">&gt;&gt;&gt; from serde.json import to_json
+&gt;&gt;&gt; to_json(Foo(i=10, s='foo', f=100.0, b=True))
 '{"i":10,"s":"foo","f":100.0,"b":true}'
 </code></pre>
 <p>You can deserialize JSON into <code>Foo</code> object.</p>
-<pre><code class="language-python">&gt;&gt;&gt; from_json(Foo, '{"i": 10, "s": "foo", "f": 100.0, "b": true}')
+<pre><code class="language-python">&gt;&gt;&gt; from serde.json import from_json
+&gt;&gt;&gt; from_json(Foo, '{"i": 10, "s": "foo", "f": 100.0, "b": true}')
 Foo(i=10, s='foo', f=100.0, b=True)
 </code></pre>
+<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
+<ul>
+<li><a href="getting-started.html">Getting started</a></li>
+<li><a href="https://yukinarit.github.io/pyserde/api/serde.html">API Reference</a></li>
+<li><a href="https://github.com/yukinarit/pyserde/tree/main/examples">Examples</a></li>
+<li><a href="faq.html">FAQ</a></li>
+</ul>
 
                     </main>
 

diff --git a/guide/en/introduction.html b/guide/en/introduction.html
@@ -150,7 +150,7 @@ <h1 class="menu-title">pyserde documentation</h1>
                         <a href="https://github.com/yukinarit/pyserde" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
-                        <a href="https://github.com/yukinarit/pyserde/edit/main/en/.//introduction.md" title="Suggest an edit" aria-label="Suggest an edit">
+                        <a href="https://github.com/yukinarit/pyserde/edit/main/docs/en/.//introduction.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>
 
@@ -180,22 +180,34 @@ <h1 class="menu-title">pyserde documentation</h1>
                 <div id="content" class="content">
                     <main>
                         <h1 id="introduction"><a class="header" href="#introduction">Introduction</a></h1>
-<p><code>pyserde</code> is a simple yet powerful serialization library on top of <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses</a>. Simply adding pyserde's <code>@serde</code> decorator makes your class (de)serializable from/to many data formats.</p>
-<pre><code class="language-python">@serde
+<p><code>pyserde</code> is a simple yet powerful serialization library on top of <a href="https://docs.python.org/3/library/dataclasses.html">dataclasses</a>. It allows you to convert Python objects to and from JSON, YAML, and other formats easily and efficiently.</p>
+<p>Declare your class with <code>@serde</code> decorator and annotate fields using <a href="https://peps.python.org/pep-0484/">PEP484</a> as below.</p>
+<pre><code class="language-python">from serde import serde
+
+@serde
 class Foo:
     i: int
     s: str
     f: float
     b: bool
 </code></pre>
 <p>You can serialize <code>Foo</code> object into JSON.</p>
-<pre><code class="language-python">&gt;&gt;&gt; to_json(Foo(i=10, s='foo', f=100.0, b=True))
+<pre><code class="language-python">&gt;&gt;&gt; from serde.json import to_json
+&gt;&gt;&gt; to_json(Foo(i=10, s='foo', f=100.0, b=True))
 '{"i":10,"s":"foo","f":100.0,"b":true}'
 </code></pre>
 <p>You can deserialize JSON into <code>Foo</code> object.</p>
-<pre><code class="language-python">&gt;&gt;&gt; from_json(Foo, '{"i": 10, "s": "foo", "f": 100.0, "b": true}')
+<pre><code class="language-python">&gt;&gt;&gt; from serde.json import from_json
+&gt;&gt;&gt; from_json(Foo, '{"i": 10, "s": "foo", "f": 100.0, "b": true}')
 Foo(i=10, s='foo', f=100.0, b=True)
 </code></pre>
+<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
+<ul>
+<li><a href="getting-started.html">Getting started</a></li>
+<li><a href="https://yukinarit.github.io/pyserde/api/serde.html">API Reference</a></li>
+<li><a href="https://github.com/yukinarit/pyserde/tree/main/examples">Examples</a></li>
+<li><a href="faq.html">FAQ</a></li>
+</ul>
 
                     </main>