docs: extend docs and add autodoc api docs

docs/api.rst

@@ -0,0 +1,4 @@
+API Reference
+====
+
+.. automodule::graphene_sqlalchemy

docs/index.rst

@@ -6,6 +6,9 @@ Contents:
 .. toctree::
  :maxdepth: 0
 
- tutorial
+ starter
+ inheritance
  tips
  examples
+ tutorial
+ api

docs/inheritance.rst

@@ -3,7 +3,7 @@ Inheritance Examples
 
 Create interfaces from inheritance relationships
 ------------------------------------------------
-.. note:: If you're using `AsyncSession`, please check the chapter `Eager Loading & Using with AsyncSession`_.
+.. note:: If you're using `AsyncSession`, please check the section `Eager Loading & Using with AsyncSession`_.
 SQLAlchemy has excellent support for class inheritance hierarchies.
 These hierarchies can be represented in your GraphQL schema by means
 of interfaces_. Much like ObjectTypes, Interfaces in

docs/relay.rst

@@ -0,0 +1,43 @@
+Relay
+====
+
+:code:`graphene-sqlalchemy` comes with pre-defined
+connection fields to quickly create a functioning relay API.
+Using the :code:`SQLAlchemyConnectionField`, you have access to relay pagination,
+sorting and filtering (filtering is coming soon!).
+
+To be used in a relay connection, your :code:`SQLAlchemyObjectType` must implement
+the :code:`Node` interface from :code:`graphene.relay`. This handles the creation of
+the :code:`Connection` and :code:`Edge` types automatically.
+
+The following example creates a relay-paginated connection:
+
+
+
+.. code:: python
+
+ class Pet(Base):
+ __tablename__ = 'pets'
+ id = Column(Integer(), primary_key=True)
+ name = Column(String(30))
+ pet_kind = Column(Enum('cat', 'dog', name='pet_kind'), nullable=False)
+
+
+ class PetNode(SQLAlchemyObjectType):
+ class Meta:
+ model = Pet
+ interfaces=(Node,)
+
+
+ class Query(ObjectType):
+ all_pets = SQLAlchemyConnectionField(PetNode.connection)
+
+To disable sorting on the connection, you can set :code:`sort` to :code:`None` the
+:code:`SQLAlchemyConnectionField`:
+
+
+.. code:: python
+
+ class Query(ObjectType):
+ all_pets = SQLAlchemyConnectionField(PetNode.connection, sort=None)
+

docs/starter.rst

@@ -0,0 +1,118 @@
+Getting Started
+====
+
+Welcome to the graphene-sqlalchemy documentation!
+Graphene is a powerful Python library for building GraphQL APIs,
+and SQLAlchemy is a popular ORM (Object-Relational Mapping)
+tool for working with databases. When combined, graphene-sqlalchemy
+allows developers to quickly and easily create a GraphQL API that
+seamlessly interacts with a SQLAlchemy-managed database.
+It is fully compatible with SQLAlchemy 1.4 and 2.0.
+This documentation provides detailed instructions on how to get
+started with graphene-sqlalchemy, including installation, setup,
+and usage examples.
+
+Installation
+------------
+
+To install :code:`graphene-sqlalchemy`, just run this command in your shell:
+
+.. code:: bash
+
+ pip install --pre "graphene-sqlalchemy"
+
+Examples
+--------
+
+Here is a simple SQLAlchemy model:
+
+.. code:: python
+
+ from sqlalchemy import Column, Integer, String
+ from sqlalchemy.ext.declarative import declarative_base
+
+ Base = declarative_base()
+
+ class UserModel(Base):
+ __tablename__ = 'user'
+ id = Column(Integer, primary_key=True)
+ name = Column(String)
+ last_name = Column(String)
+
+To create a GraphQL schema for it, you simply have to write the
+following:
+
+.. code:: python
+
+ import graphene
+ from graphene_sqlalchemy import SQLAlchemyObjectType
+
+ class User(SQLAlchemyObjectType):
+ class Meta:
+ model = UserModel
+ # use `only_fields` to only expose specific fields ie "name"
+ # only_fields = ("name",)
+ # use `exclude_fields` to exclude specific fields ie "last_name"
+ # exclude_fields = ("last_name",)
+
+ class Query(graphene.ObjectType):
+ users = graphene.List(User)
+
+ def resolve_users(self, info):
+ query = User.get_query(info) # SQLAlchemy query
+ return query.all()
+
+ schema = graphene.Schema(query=Query)
+
+Then you can simply query the schema:
+
+.. code:: python
+
+ query = '''
+ query {
+ users {
+ name,
+ lastName
+ }
+ }
+ '''
+ result = schema.execute(query, context_value={'session': db_session})
+
+
+It is important to provide a session for graphene-sqlalchemy to resolve the models.
+In this example, it is provided using the GraphQL context. See :ref:`querying` for
+other ways to implement this.
+
+You may also subclass SQLAlchemyObjectType by providing
+``abstract = True`` in your subclasses Meta:
+
+.. code:: python
+
+ from graphene_sqlalchemy import SQLAlchemyObjectType
+
+ class ActiveSQLAlchemyObjectType(SQLAlchemyObjectType):
+ class Meta:
+ abstract = True
+
+ @classmethod
+ def get_node(cls, info, id):
+ return cls.get_query(info).filter(
+ and_(cls._meta.model.deleted_at==None,
+ cls._meta.model.id==id)
+ ).first()
+
+ class User(ActiveSQLAlchemyObjectType):
+ class Meta:
+ model = UserModel
+
+ class Query(graphene.ObjectType):
+ users = graphene.List(User)
+
+ def resolve_users(self, info):
+ query = User.get_query(info) # SQLAlchemy query
+ return query.all()
+
+ schema = graphene.Schema(query=Query)
+
+More complex inhertiance using SQLAlchemy's polymorphic models is also supported.
+You can check out :doc:`inheritance` for a guide.

docs/tips.rst

@@ -4,7 +4,7 @@ Tips
 
 Querying
 --------
-
+.. _querying:
 In order to make querying against the database work, there are two alternatives:
 
 - Set the db session when you do the execution: