From c4c3d0ef284c6eece719d25543fa83ecdcf5a244 Mon Sep 17 00:00:00 2001 From: Syrus Akbary Date: Wed, 25 Nov 2015 22:58:43 -0800 Subject: [PATCH] Improved documentation pages. --- .travis.yml | 2 +- docs/css/main.styl | 19 +++++++-- docs/pages/community.md | 7 +++- docs/pages/docs/_template.js | 58 ++++++++++++++++------------ docs/pages/docs/basic-types.md | 12 ++---- docs/pages/docs/interfaces.md | 2 +- docs/pages/docs/objecttypes.md | 2 +- docs/pages/docs/quickstart-django.md | 10 +++-- docs/pages/docs/quickstart.md | 11 +----- docs/pages/index.md | 8 +--- docs/wrappers/md.js | 8 ++-- 11 files changed, 78 insertions(+), 61 deletions(-) diff --git a/.travis.yml b/.travis.yml index 48fd46be..d948d340 100644 --- a/.travis.yml +++ b/.travis.yml @@ -32,7 +32,7 @@ install: script: - | if [ "$TEST_TYPE" = build_website ]; then - if [ "$TRAVIS_BRANCH" = "docs" ] && [ "$TRAVIS_PULL_REQUEST" = false ]; then + if [ "$TRAVIS_BRANCH" = "master" ] && [ "$TRAVIS_PULL_REQUEST" = false ]; then echo "Building the web." nvm install 4.0 diff --git a/docs/css/main.styl b/docs/css/main.styl index 3bdd3bcd..fd7e3c43 100644 --- a/docs/css/main.styl +++ b/docs/css/main.styl @@ -19,6 +19,9 @@ a, a:hover a color rgb(42,93,173) +p + margin-bottom 1em + html, body font-family "Helvetica Neue", Helvetica, Arial, sans-serif font-weight 300 @@ -283,6 +286,10 @@ $title border-radius 2px border 1px solid #CCC color #000 + p + p, p + ul + margin-top -.4em + p + ul + margin-top -.6em code font-size 14px line-height 20px @@ -295,16 +302,16 @@ $title .title background: #F9F9F9; - padding 54px 0 + padding 48px 0 h1 margin 0 auto @extend $wrapper font-family: 'Raleway'; - font-size: 42px; + font-size: 40px; font-weight 200 color: #585858; - line-height: 49px; + line-height: 50px; .docs @extend $wrapper @@ -356,6 +363,7 @@ $title .docs-content col(3/4) margin-top 60px + margin-bottom 20px +below(600px) margin-top 10px col(1) @@ -364,3 +372,8 @@ $title margin 0 @extend $title font-size 32px + + .docs-next + float right + color #e05b49 + font-weight 400 diff --git a/docs/pages/community.md b/docs/pages/community.md index c42f6b2b..20d747a7 100644 --- a/docs/pages/community.md +++ b/docs/pages/community.md @@ -5,7 +5,7 @@ active_tab: community description: The biggest GraphQL Community in Python --- -Graphene is constantly developing thanks to an active volunteer community, There are many different places where you discuss Graphene, share your experiences or ask for help. Your feedback and participation are very welcome! +Graphene is constantly developing thanks to an active volunteer community, There are many different places where you discuss Graphene, share your experiences or ask for help. **Your feedback and participation are very welcome**! If you think working with Graphene is fun, there are many ways you can contribute to it. Please join us in the Slack community and help us shape the next generation API’s. @@ -21,6 +21,11 @@ Django integration: - **graphql-django-view**: [Source Code][5] - [PyPI package][6] - **django-graphiql**: [Source Code][7] - [PyPI package][8] +## Other related projects + +- [Flask GraphQL Demo](https://github.com/amitsaha/flask-graphql-demo) by [@echorand](https://twitter.com/echorand) + + [Source Code]: https://github.com/graphql-python/graphql-core [PyPI package]: https://pypi.python.org/pypi/graphql-core [1]: https://github.com/graphql-python/graphql-relay diff --git a/docs/pages/docs/_template.js b/docs/pages/docs/_template.js index c678e494..d25d0d3e 100644 --- a/docs/pages/docs/_template.js +++ b/docs/pages/docs/_template.js @@ -10,31 +10,41 @@ class Template extends React.Component { render() { var docs = this.props.config.docs; var docs_index = _.indexBy(this.props.pages, 'path'); - return ( -
- -
- +
; + }); + var aside_options = Object.keys(docs).map((key) => { + let group = docs[key]; + return + {group.pages.map((page) => { + return + })} + ; + }); + var next_page_index = pages.indexOf(this.props.page.path)+1; + var next_page = pages[next_page_index]; + return ( +
+

Documentation

+
+ +
+ + {next_page?Next - {docs_index[next_page].data.title} →:null} +
); diff --git a/docs/pages/docs/basic-types.md b/docs/pages/docs/basic-types.md index 50e96e86..b1acb2f6 100644 --- a/docs/pages/docs/basic-types.md +++ b/docs/pages/docs/basic-types.md @@ -62,29 +62,23 @@ class DateTime(Scalar): This types if are mounted in a `ObjectType`, `Interface` or `Mutation`, would act as `Field`s. -So, the following examples will behave exactly the same: ```python class Person(graphene.ObjectType): name = graphene.String() -``` -and -```python +# Is equivalent to: class Person(graphene.ObjectType): name = graphene.Field(graphene.String()) ``` ## Mounting in Fields -If this types are mounted in a `Field`, would act as `Argument`s. -So, the following examples will behave exactly the same: +If the types are mounted in a `Field`, would act as `Argument`s. ```python graphene.Field(graphene.String(), to=graphene.String()) -``` -and -```python +# Is equivalent to: graphene.Field(graphene.String(), to=graphene.Argument(graphene.String())) ``` diff --git a/docs/pages/docs/interfaces.md b/docs/pages/docs/interfaces.md index 43c2daf8..b6e61743 100644 --- a/docs/pages/docs/interfaces.md +++ b/docs/pages/docs/interfaces.md @@ -8,7 +8,7 @@ description: Walkthrough Interfaces An Interface contains the essential fields that will be shared among multiple ObjectTypes. The basics: -- Each Interface is a Python class that inherits from graphene.Interface. +- Each Interface is a Python class that inherits from `graphene.Interface`. - Each attribute of the Interface represents a GraphQL field. ## Quick example diff --git a/docs/pages/docs/objecttypes.md b/docs/pages/docs/objecttypes.md index 897b50f0..b1c59663 100644 --- a/docs/pages/docs/objecttypes.md +++ b/docs/pages/docs/objecttypes.md @@ -8,7 +8,7 @@ description: Walkthrough ObjectTypes An ObjectType is the single, definitive source of information about your data. It contains the essential fields and behaviors of the data you’re querying. The basics: -- Each ObjectType is a Python class that inherits graphene.ObjectType or inherits an implemented [Interface](/docs/interfaces/). +- Each ObjectType is a Python class that inherits `graphene.ObjectType` or inherits an implemented [Interface](/docs/interfaces/). - Each attribute of the ObjectType represents a GraphQL field. ## Quick example diff --git a/docs/pages/docs/quickstart-django.md b/docs/pages/docs/quickstart-django.md index 542854e7..2b6020d0 100644 --- a/docs/pages/docs/quickstart-django.md +++ b/docs/pages/docs/quickstart-django.md @@ -1,10 +1,14 @@ --- -title: Guide to Django +title: Django Tutorial description: A Quick guide to Graphene in Django --- +# Django Tutorial + In our previous quickstart page we created a very simple schema. -Now we will adapt the schema to map automatically some Django models. + +Now we will adapt the schema to map automatically some Django models, +and expose this schema in a `/graphql` API endpoint. ## Project setup @@ -54,7 +58,7 @@ from graphene.contrib.django import DjangoObjectType from django.contrib.auth.models import User, Group -# Graphene will map automaticall the User model to UserType with +# Graphene will map automatically the User model to UserType with # the specified fields class UserType(DjangoObjectType): class Meta: diff --git a/docs/pages/docs/quickstart.md b/docs/pages/docs/quickstart.md index f2c56f03..74d574d2 100644 --- a/docs/pages/docs/quickstart.md +++ b/docs/pages/docs/quickstart.md @@ -3,6 +3,8 @@ title: Getting started description: A Quick guide to Graphene --- +# Getting started + Let's build a basic GraphQL schema from scratch. @@ -15,15 +17,6 @@ Let's build a basic GraphQL schema from scratch. ## Project setup ```bash -# Create the project directory -mkdir tutorial -cd tutorial - -# Create a virtualenv to isolate our package dependencies locally -virtualenv env -source env/bin/activate # On Windows use `env\Scripts\activate` - -# Install Graphene pip install graphene ``` diff --git a/docs/pages/index.md b/docs/pages/index.md index 359e512b..880dc27c 100644 --- a/docs/pages/index.md +++ b/docs/pages/index.md @@ -3,12 +3,8 @@ path: / ---
Check our Django Starwars API example!
-## About Graphene +## Meet Graphene Graphene is a Python library for building GraphQL schemas/types fast and easily. -**What is GraphQL?** A GraphQL query is a string interpreted by a server that returns data in a specified format. - -- **Easy to use:** Graphene helps you use GraphQL in Python without effort. -- **Relay:** Graphene has builtin support for Relay -- **Django:** Automatic *Django model* mapping to Graphene Types. +**But, what is GraphQL?** A GraphQL query is a string interpreted by a server that returns data in a specified format. We believe *GraphQL* is the next big thing after peanut butter and *REST*. diff --git a/docs/wrappers/md.js b/docs/wrappers/md.js index b34806c3..67df0e37 100644 --- a/docs/wrappers/md.js +++ b/docs/wrappers/md.js @@ -12,12 +12,14 @@ class Markdown extends React.Component { var showTitle = post.title && !this.props.docs; return ( -
+
{showTitle?

{post.title}

:null} -
- Edit page +
+
+ Edit page +
);