Add general documentation

[bruno-f-cruz]

I am opening this issue to create a point for centralized discussion for a first draft of this tool's documentation. My current idea is to work around the following structure:

• General documentation

  • What is Bonsai.Sgen
  • Why you may want to use Sgen / what problems does it solve
  • What do you gain in Bonsai?
  • Setting up (local dotnet tool deployment + setting up Extensions csproj)

• Basic Sgen usage (each topic should follow the same structure where the json-schema shows

  • Simple json-schema examples with non-hierarchical models
  • json-schema example with simple nested model
  • Enums
  • Lists
  • Serialization and Deserialization (Explain json and yaml)
  • Namespaces

• Advanced usage:

  • Discriminated Unions and the Match operator
  • On the use of partial
  • Copying and modifying objects (May benefit from a bit more polishing from the package side)
  • Advanced logging patterns (generics and mux patterns) (out of scope)
  • extension tags (x-abstract, x-enum-names, others?)

• Experimental (not sure if this section should even be included, but the idea is to provide examples of interactions that "may" work but are not officially supported);

  • Using pydantic to compile json-schema
  • Full trip (de)serialization (python -> json -> bonsai -> json -> python)
    (decided to remove this section as it will probably locks us into supporting something that we are currently not comitted to support, we should talk about it tho).