Update reference documentation

docs/reference/client/example.rst

@@ -5,9 +5,9 @@ A simple aiosnow application
 
 .. code-block:: python
 
-    from aiosnow import Client
+    import aiosnow
 
-    app = Client(
-        "https://my-instance.service-now.com",
+    snow = aiosnow.Client(
+        "<instance-name>.service-now.com",
         basic_auth=("<username>", "<password>")
     )

docs/reference/client/index.rst

@@ -3,8 +3,8 @@
 Client
 ======
 
-The :class:`~aiosnow.Client` constructor takes a set of config parameters and provides an interface for
-producing API Models and more.
+The :class:`~aiosnow.Client` constructor takes a set of config parameters and provides methods for
+interacting with ServiceNow APIs.
 
 API
 ---

docs/reference/models/index.rst

@@ -6,7 +6,7 @@ Models
 To perform API operations, a Model object must first be created. This is done either via a :class:`~aiosnow.Client` factory
 method, or by importing and instantiating the desired concrete Model directly.
 
-Concrete built-in Models, such as those of :class:`~aiosnow.models.TableModel` type, are modelled after default ServiceNow API resources.
+Concrete built-in Models, such as those of :class:`~aiosnow.models.table.TableModel` type, are modelled after default ServiceNow API resources.
 
 
 .. toctree::

docs/reference/models/table/example.rst

@@ -6,9 +6,10 @@ factory method for producing a :class:`~aiosnow.models.table.TableModel`.
 
 .. code-block:: python
 
-    from aiosnow import Client, model
+    import aiosnow
+    from aiosnow.schemas.table import IncidentSchema
 
-    class Incident(model.schema.TableSchema):
+    class Incident(IncidentSchema):
         class Meta:
             table_name = "incident"
 
@@ -20,14 +21,13 @@ factory method for producing a :class:`~aiosnow.models.table.TableModel`.
         assignment_group = fields.TextMap()
         opened_at = fields.DateTime()
 
-    app = Client(
-        "https://my-instance.service-now.com",
+    snow = Client(
+        "https://<instance-name>.service-now.com",
         basic_auth=("<username>", "<password>")
     )
 
-    # Produce a TableModel object using the built-in Incident schema
-    async with app.get_table(Incident) as r:
+    # Produce a TableModel object using a modified IncidentSchema
+    async with snow.get_table(Incident) as inc:
         # Get incident with number INC01234
-        response = await r.get_one(Incident.number == "INC01234")
+        response = await inc.get_one(Incident.number == "INC01234")
         print(response["description"])
-

docs/reference/models/table/index.rst

@@ -2,7 +2,7 @@ Table
 =====
 
 Objects of this type are typically created via :meth:`~aiosnow.Client.get_table`
-(given a :class:`~aiosnow.models.TableSchema`) and provides an interface for working with the ServiceNow Table API.
+(given a :class:`~aiosnow.models.table.TableSchema`) and provides an interface for working with the ServiceNow Table API.
 
 
 API

docs/reference/models/table/schema.rst

@@ -1,7 +1,7 @@
 Schema
 ======
 
-The TableSchema functions like a regular schema, but requires :attr:`~aiosnow.models.table.TableSchema.Meta.table_name`
+The TableSchema behaves like a regular schema, but requires :attr:`~aiosnow.models.table.TableSchema.Meta.table_name`
 to be set in the :class:`~aiosnow.models.table.TableSchema.Meta` inner class.
 
 
@@ -21,7 +21,7 @@ Example
 
     class Incident(model.table.TableSchema):
         class Meta:
-            table_name = "incident"
+            table_name = "incident"  # Note
 
         field1 = fields.Text()
 

docs/reference/schema/base.rst

@@ -1,7 +1,8 @@
 Base
 ====
 
-The :class:`~aiosnow.model.schema.BaseSchema` class is mainly used for defining new model types.
+The :class:`~aiosnow.model.schema.BaseSchema` class is mainly used for defining new model types - useful for defining
+custom APIs.
 
 API
 ---

docs/reference/schema/index.rst

@@ -6,7 +6,7 @@ Schema
 Schemas are used for describing API models using :ref:`fields <fields-root>` and the :class:`~aiosnow.model.schema.BaseSchema.Meta`
 inner class for type-specific configuration, such as `table_name` in the :class:`~aiosnow.models.table.TableSchema` class.
 
-Check out the :ref:`built-in schemas <schemas-root>` if you're looking to get started quickly.
+Check out the :ref:`default schemas <schemas-root>` if you're looking to get started quickly.
 
 
 .. toctree::

docs/reference/schema/partial.rst

@@ -4,7 +4,6 @@ Partial
 Schemas can be nested with the special :class:`~aiosnow.model.schema.PartialSchema` class, which doesn't require a
 Meta inner class.
 
-When registered as a field, as illustrated in the example below, the nested fields can be queried as well.
 
 Example
 -------
@@ -13,20 +12,12 @@ TableSchema with nested assignment_group
 
 .. code-block:: python
 
-    from aiosnow.model.schema import TableSchema, PartialSchema, fields
+    from aiosnow.model.schema import PartialSchema, fields
+    from aiosnow.schemas.table.incident import IncidentSchema
 
     class AssignmentGroup(PartialSchema):
         name = fields.Text()
         manager = fields.Text()
 
-    class Incident(TableSchema):
-        class Meta:
-            table_name = "incident"
-
-        sys_id = fields.Text(is_primary=True)
-        number = fields.Text()
-        description = fields.Text()
-        short_description = fields.Text()
-        impact = fields.Numeric()
-        assignment_group = AssignmentGroup
-        opened_at = fields.DateTime()
+    class Incident(IncidentSchema):
+        assignment_group = AssignmentGroup  # override with a partial schema