Completed documentation

Author: Sylvain MARIE

docs/index.md

@@ -26,6 +26,10 @@ In addition `yamlable` provides a way to create Yaml codecs for several object t
 
 ## Usage
 
+### 1. The (recommended) `YamlAble` way
+
+#### a. Creating the class
+
 Let's make a class yaml-able: we have to
 
  - inherit from `YamlAble`
@@ -38,7 +42,7 @@ from yamlable import yaml_info, YamlAble
 @yaml_info(yaml_tag_ns='com.yamlable.example')
 class Foo(YamlAble):
 
-    def __init__(self, a, b):
+    def __init__(self, a, b="hey"):
         """ Constructor """
         self.a = a
         self.b = b
@@ -67,6 +71,8 @@ That's it! Let's check that our class is correct and allows us to create instanc
 Foo - {'a': 1, 'b': 'hello'}
 ```
 
+#### b. Dumping and loading to/from YAML
+
 Now let's dump and load it using `pyyaml`:
 
 ```python
@@ -105,7 +111,44 @@ a: 1
 b: hello
 ```
 
-See [Usage](./usage) for other possibilities of `yamlable`.
+#### c. Support for sequences and scalars
+
+Objects can also be loaded from YAML sequences:
+
+```python
+>>> print(yaml.safe_load("""
+!yamlable/com.yamlable.example.Foo
+- 0
+- hey
+"""))
+
+Foo - {'a': 0, 'b': 'hey'}
+```
+
+The default implementation of `__from_yaml_sequence__` (that you may wish to override in your subclass), is to call
+the constructor with the sequence contents as positional arguments.
+
+The same also works for scalars:
+
+```python
+>>> print(yaml.safe_load("""
+!yamlable/com.yamlable.example.Foo 0
+"""))
+
+Foo - {'a': "0", 'b': 'hey'}
+```
+
+The default implementation of `__from_yaml_scalar__` (that you may wish to override in your subclass), is to call
+the constructor with the scalar as first positional argument.
+
+!!! warning "Scalars are not resolved"
+    As can be seen in the above example, scalars are not auto-resolved when constructing an object from a scalar. So an
+    integer `0` is actually received as a string `"0"` by `from_yaml_scalar`.
+
+
+#### d. What if you can not modify the class ?
+
+See [Usage](./usage#yamlcodec) for another possibility offered by `yamlable`: creating a codec to handle YAML for several classes at once, typically classes that you cannot modify.
 
 
 ## Main features / benefits

docs/usage.md

@@ -4,6 +4,8 @@ You have seen in the [main page](./index) a small example to understand the conc
 
 ## `YamlCodec`
 
+### 1. Writing a codec class
+
 Sometimes you do not have the possibility to change the classes of the objects that you wish to encode/decode. In this case the solution is to write an independent codec, inheriting from `YamlCodec`. Once again this feature leverages the `multi_constructor` and `multi_representer` concepts available in the `PyYaml` internals, but with `YamlCodec` it becomes a bit easier to do.
 
 Let's assume that the following two classes are given and can not be modified:
@@ -84,13 +86,17 @@ class MyCodec(YamlCodec):
         return types_to_yaml_tags[type(obj)], vars(obj)
 ```
 
+### 2. Registering a codec
+
 When you codec has been defined, it needs to be registerd before being usable. You can specify with which `PyYaml` Loaders/Dumpers it should be registered, or use the default (all): 
 
 ```python
 # register the codec
 MyCodec.register_with_pyyaml()
 ```
 
+### 3. Using a codec
+
 Finally let's test that the codec works:
 
 ```python
@@ -111,3 +117,10 @@ assert dump(b) == by
 assert f == load(fy)
 assert b == load(by)
 ```
+
+### 4. Sequences and scalars
+
+Objects can be loaded from sequences and scalars, in addition to dictionaries. To support this possibility, you simply need to fill the class methods:
+
+ - `from_yaml_sequence` for sequences
+ - `from_yaml_scalar` for scalars

docs/mkdocs.yml mkdocs.ymldocs/mkdocs.yml renamed to mkdocs.yml

@@ -1,8 +1,10 @@
 site_name: yamlable
 # site_description: 'A short description of my project'
 repo_url: https://github.com/smarie/python-yamlable
-docs_dir: .
-site_dir: ../site
+# docs_dir: .
+# site_dir: ../site
+# default branch is main instead of master now on github
+edit_uri : ./edit/main/docs
 nav:
     - Home: index.md
     - Usage details: usage.md