improve documentation

Author: hendrikboeck

README.md

@@ -33,6 +33,8 @@
 - [Why?](#why)
 - [What about the name?](#what-about-the-name)
 - [Getting Started](#getting-started)
+  - [Installing](#installing)
+  - [Example usage](#example-usage)
 - [Documentation](#documentation)
 - [License (_MIT License_)](#license-mit-license)
 
@@ -55,15 +57,17 @@ library that inspired this creation.
 
 ## Getting Started
 
+### Installing
+
 Install using `pip`:
 
-```
+```sh
 pip install parasite
 ```
 
 Install using `poetry` CLI:
 
-```
+```sh
 poetry add parasite
 ```
 
@@ -74,10 +78,31 @@ or using `pyproject.toml`:
 parasite = "^0.1.0"
 ```
 
+### Example usage
+
+```python
+from parasite import p
+
+schema = p.obj({
+    "name": p.string().required(),
+    "age": p.number().integer().min(0).optional(),
+}).strip()
+
+data = {
+    "name": "John Doe",
+    "age": 42,
+    "extra": "This will be stripped",
+}
+
+schema.parse(data)   # {'name': 'John Doe', 'age': 42}
+schema.parse({})   # ValidationError: Missing required key: 'name'
+```
+
 ## Documentation
 
 > [!IMPORTANT]
-> Work in Progress...
+>
+> You can find the sphinx online documentation [here](https://hendrikboeck.github.io/parasite)!
 
 ## License (_MIT License_)
 

docs/source/apidocs/index.rst

@@ -1,6 +1,9 @@
-############################
-``_const`` Private Submodule
-############################
+###################
+``parasite._const``
+###################
+
+Member Reference
+================
 
 .. automodule:: parasite._const
    :members:

docs/source/apidocs/pkg_parasite/_const.rst

@@ -0,0 +1,12 @@
+############
+``parasite``
+############
+
+Member Reference
+================
+
+.. automodule:: parasite
+    :members:
+    :inherited-members:
+    :undoc-members:
+    :show-inheritance:

docs/source/apidocs/pkg_parasite/_root.rst

@@ -1,6 +1,6 @@
-###########################
-``any`` Submodule Reference
-###########################
+################
+``parasite.any``
+################
 
 Brief
 =====

docs/source/apidocs/pkg_parasite/any.rst

@@ -1,6 +1,6 @@
-#############################
-``array`` Submodule Reference
-#############################
+##################
+``parasite.array``
+##################
 
 Brief
 =====

docs/source/apidocs/pkg_parasite/array.rst

@@ -1,6 +1,6 @@
-###############################
-``boolean`` Submodule Reference
-###############################
+####################
+``parasite.boolean``
+####################
 
 Brief
 =====

docs/source/apidocs/pkg_parasite/boolean.rst

@@ -1,6 +1,6 @@
-##############################
-``errors`` Submodule Reference
-##############################
+###################
+``parasite.errors``
+###################
 
 Brief
 =====

docs/source/apidocs/pkg_parasite/errors.rst

@@ -1,23 +1,23 @@
-####################
-``parasite`` Package
-####################
+.. _apidocs:
 
-Module API
-==========
+#############
+API Reference
+#############
 
-.. automodule:: parasite
-    :members:
-    :undoc-members:
-    :show-inheritance:
+This section documents the API of the ``parasite`` package. Use the links below to
+navigate the code documentation.
 
-Module Reference
-================
+Modules
+=======
 
 .. toctree::
    :maxdepth: 3
 
+   _root
    _const
    errors
    any
    array
    boolean
+   never
+   object

docs/source/apidocs/pkg_parasite/index.rst

@@ -0,0 +1,35 @@
+##################
+``parasite.never``
+##################
+
+Brief
+=====
+
+Reference for the ``never`` submodule of the ``parasite`` package. This submodule
+contains the :class:`Never` class, which is a simple class that always raises a
+:class:`ValidationError` when called.
+
+Usage
+=====
+
+.. code-block:: python
+
+   from parasite import p
+
+   schema = p.never()
+   schema.parse(1)  # ValidationError: this type can never be parsed
+   ...
+
+   schema = p.obj({ "name": p.never() })
+   schema.parse({ "name": "John" })  # ValidationError: key 'name' found, but this type can never be parsed
+   ...
+
+Member Reference
+================
+
+.. automodule:: parasite.never
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+

docs/source/apidocs/pkg_parasite/never.rst

@@ -0,0 +1,37 @@
+###################
+``parasite.object``
+###################
+
+Brief
+=====
+
+Reference for the ``object`` submodule of the ``parasite`` package. This submodule
+contains the :class:`Object` class, which is a generic container for a dictionary Python object.
+
+Usage
+=====
+
+.. code-block:: python
+
+   from parasite import p
+
+   schema = p.obj({
+      "name": p.string(),
+      "age": p.number().integer().min(0),
+   }).strict()
+
+   schema.parse({
+      "name": "John",
+      "age": 30,
+   })  # -> {'name': 'John', 'age': 30 }
+   ...
+
+Member Reference
+================
+
+.. automodule:: parasite.object
+   :members:
+   :inherited-members:
+   :undoc-members:
+   :show-inheritance:
+

docs/source/apidocs/pkg_parasite/object.rst

@@ -14,7 +14,7 @@
 project = 'Parasite'
 copyright = f'2024-{datetime.date.today().year}, Hendrik Boeck <hendrikboeck.dev@protonmail.com>'
 author = 'Hendrik Boeck <hendrikboeck.dev@protonmail.com>'
-release = 'v0.1.5'
+release = 'v0.1.6'
 html_title = f"{project} {release}"
 
 # -- General configuration ---------------------------------------------------
@@ -30,9 +30,13 @@
 templates_path = ['_templates']
 exclude_patterns = []
 
+pygments_style = "emacs"
+pygments_dark_style = "one-dark"
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 html_theme = 'qiskit-ecosystem'
+# html_theme = 'furo'
 html_static_path = ['_static']
 html_logo = "_static/parasite-logo.png"
 

docs/source/conf.py

@@ -9,7 +9,7 @@ Welcome to Parasite's documentation!
 .. toctree::
    :hidden:
 
-   API Reference <apidocs/index>
+   API Reference <apidocs/pkg_parasite/index>
    GitHub <https://github.com/hendrikboeck/parasite>
 
 .. Documentation Home <index>

docs/source/index.rst

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "parasite"
-version = "0.1.5"
+version = "0.1.6"
 description = "Data validation for Python 3"
 authors = ["Hendrik Boeck <hendrikboeck.dev@protonmail.com>"]
 packages = [{ include = "*", from = "src" }]

pyproject.toml

@@ -19,7 +19,7 @@ class p(_Namespace):
     sudo-namespace for all parasite types. Makes it easier to import and call them. Tries to mimic
     the behavior of the ``z`` object imported from ``zod`` library in JavaScript.
 
-    Example::
+    Example usage::
 
         >>> from parasite import p
         >>>

src/parasite/__init__.py

@@ -37,22 +37,46 @@ def __init__(self) -> None:
 
     def optional(self) -> Any_:
         """
-        Makes the value optional, when parsing with ``_find_and_parse(..)``. Has no effect on
-        ``parse(..)``. Inverse of ``required(..)``.
+        Makes the value optional, when parsing with :func:`_find_and_parse`. Has no effect on
+        :func:`parse`. Inverse of :func:`required`.
 
         Returns:
             Any_: modified instance
+
+        Example usage::
+
+            from parasite import p
+
+            schema = p.obj({ "name": p.any() })
+            schema.parse({ "name": "John" })  # -> { "name": "John" }
+            schema.parse({ })  # -> ValidationError: key 'name' not found, but is required
+
+            schema = p.obj({ "name": p.any().optional() })
+            schema.parse({ "name": "John" })  # -> { "name": "John" }
+            schema.parse({ })  # -> { }
         """
         self._f_optional = True
         return self
 
     def required(self) -> Any_:
         """
-        Makes the value required, when parsing with ``_find_and_parse(..)``. Has no effect on
-        ``parse(..)``. Inverse of ``optional(..)``. Default behavior.
+        Makes the value required, when parsing with :func:`_find_and_parse`. Has no effect on
+        :func:`parse`. Inverse of :func:`optional`. Default behavior.
 
         Returns:
             Any_: modified instance
+
+        Example usage::
+
+            from parasite import p
+
+            schema = p.obj({ "name": p.any() })
+            schema.parse({ "name": "John" })  # -> { "name": "John" }
+            schema.parse({ })  # -> ValidationError: key 'name' not found, but is required
+
+            schema = p.obj({ "name": p.any().required() })
+            schema.parse({ "name": "John" })  # -> { "name": "John" }
+            schema.parse({ })  # -> ValidationError: key 'name' not found, but is required
         """
         self._f_optional = False
         return self