Merge pull request #624 from graphql-python/docs-improvements

Docs improvements

Author: phalt

README.md

@@ -7,7 +7,11 @@ Please read [UPGRADE-v2.0.md](https://github.com/graphql-python/graphene/blob/ma
 
 A [Django](https://www.djangoproject.com/) integration for [Graphene](http://graphene-python.org/).
 
-## Installation
+## Documentation
+
+[Visit the documentation to get started!](https://docs.graphene-python.org/projects/django/en/latest/)
+
+## Quickstart
 
 For installing graphene, just run this command in your shell
 
@@ -39,7 +43,7 @@ from graphene_django.views import GraphQLView
 
 urlpatterns = [
     # ...
-    url(r'^graphql', GraphQLView.as_view(graphiql=True)),
+    url(r'^graphql$', GraphQLView.as_view(graphiql=True)),
 ]
 ```
 

README.rst

@@ -10,8 +10,14 @@ to learn how to upgrade to Graphene ``2.0``.
 A `Django <https://www.djangoproject.com/>`__ integration for
 `Graphene <http://graphene-python.org/>`__.
 
-Installation
-------------
+
+Documentation
+-------------
+
+`Visit the documentation to get started! <https://docs.graphene-python.org/projects/django/en/latest/>`__
+
+Quickstart
+----------
 
 For installing graphene, just run this command in your shell
 
@@ -46,7 +52,7 @@ serve the queries.
 
     urlpatterns = [
         # ...
-        url(r'^graphql', GraphQLView.as_view(graphiql=True)),
+        url(r'^graphql$', GraphQLView.as_view(graphiql=True)),
     ]
 
 Examples

docs/authorization.rst

@@ -155,7 +155,7 @@ To restrict users from accessing the GraphQL API page the standard Django LoginR
 
 .. code:: python
     #views.py
-    
+
     from django.contrib.auth.mixins import LoginRequiredMixin
     from graphene_django.views import GraphQLView
 
@@ -171,9 +171,9 @@ For Django 1.9 and below:
 
     urlpatterns = [
       # some other urls
-      url(r'^graphql', PrivateGraphQLView.as_view(graphiql=True, schema=schema)),
+      url(r'^graphql$', PrivateGraphQLView.as_view(graphiql=True, schema=schema)),
     ]
-    
+
 For Django 2.0 and above:
 
 .. code:: python

docs/conf.py

@@ -1,6 +1,6 @@
 import os
 
-on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+on_rtd = os.environ.get("READTHEDOCS", None) == "True"
 
 # -*- coding: utf-8 -*-
 #
@@ -34,46 +34,44 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.coverage',
-    'sphinx.ext.viewcode',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
 ]
 if not on_rtd:
-    extensions += [
-        'sphinx.ext.githubpages',
-    ]
+    extensions += ["sphinx.ext.githubpages"]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ".rst"
 
 # The encoding of source files.
 #
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'Graphene Django'
-copyright = u'Graphene 2017'
-author = u'Syrus Akbary'
+project = u"Graphene Django"
+copyright = u"Graphene 2017"
+author = u"Syrus Akbary"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'1.0'
+version = u"1.0"
 # The full version, including alpha/beta/rc tags.
-release = u'1.0.dev'
+release = u"1.0.dev"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -94,7 +92,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -116,7 +114,7 @@
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -175,7 +173,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -255,34 +253,30 @@
 # html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'Graphenedoc'
+htmlhelp_basename = "Graphenedoc"
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-     # The paper size ('letterpaper' or 'a4paper').
-     #
-     # 'papersize': 'letterpaper',
-
-     # The font size ('10pt', '11pt' or '12pt').
-     #
-     # 'pointsize': '10pt',
-
-     # Additional stuff for the LaTeX preamble.
-     #
-     # 'preamble': '',
-
-     # Latex figure (float) alignment
-     #
-     # 'figure_align': 'htbp',
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'Graphene.tex', u'Graphene Documentation',
-     u'Syrus Akbary', 'manual'),
+    (master_doc, "Graphene.tex", u"Graphene Documentation", u"Syrus Akbary", "manual")
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -323,8 +317,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'graphene_django', u'Graphene Django Documentation',
-     [author], 1)
+    (master_doc, "graphene_django", u"Graphene Django Documentation", [author], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -338,9 +331,15 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'Graphene-Django', u'Graphene Django Documentation',
-     author, 'Graphene Django', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "Graphene-Django",
+        u"Graphene Django Documentation",
+        author,
+        "Graphene Django",
+        "One line description of project.",
+        "Miscellaneous",
+    )
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -414,7 +413,7 @@
 # epub_post_files = []
 
 # A list of files that should not be packed into the epub file.
-epub_exclude_files = ['search.html']
+epub_exclude_files = ["search.html"]
 
 # The depth of the table of contents in toc.ncx.
 #
@@ -446,4 +445,4 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {"https://docs.python.org/": None}

docs/debug.rst

@@ -34,6 +34,7 @@ And in your ``settings.py``:
 .. code:: python
 
     GRAPHENE = {
+        ...
         'MIDDLEWARE': [
             'graphene_django.debug.DjangoDebugMiddleware',
         ]

docs/filtering.rst

@@ -136,7 +136,7 @@ pre-filter animals owned by the authenticated user (set in ``context.user``).
 
     class AnimalFilter(django_filters.FilterSet):
         # Do case-insensitive lookups on 'name'
-        name = django_filters.CharFilter(lookup_type='iexact')
+        name = django_filters.CharFilter(lookup_type=['iexact'])
 
         class Meta:
             model = Animal
@@ -146,3 +146,49 @@ pre-filter animals owned by the authenticated user (set in ``context.user``).
         def qs(self):
             # The query context can be found in self.request.
             return super(AnimalFilter, self).qs.filter(owner=self.request.user)
+
+
+Ordering
+--------
+
+You can use ``OrderFilter`` to define how you want your returned results to be ordered.
+
+Extend the tuple of fields if you want to order by more than one field.
+
+.. code:: python
+
+    from django_filters import FilterSet, OrderingFilter
+
+    class UserFilter(FilterSet):
+        class Meta:
+            model = UserModel
+
+        order_by = OrderingFilter(
+            fields=(
+                ('created_at', 'created_at'),
+            )
+        )
+
+    class Group(DjangoObjectType):
+      users = DjangoFilterConnectionField(Ticket, filterset_class=UserFilter)
+
+      class Meta:
+          name = 'Group'
+          model = GroupModel
+          interfaces = (relay.Node,)
+
+      def resolve_users(self, info, **kwargs):
+        return UserFilter(kwargs).qs
+
+
+with this set up, you can now order the users under group:
+
+.. code::
+
+    query {
+      group(id: "xxx") {
+        users(orderBy: "-created_at") {
+          xxx
+        }
+      }
+    }