expose livehtml autobuild in Makefile + Add API autodoc #971

dvndrsn · 2019-05-22T04:29:59Z

Autobuild was previously set up in Makefile, but did not have its requirements frozen in requirements.txt and the command was not documented well. Added API level documentation for parameters and arguments for the core graphene objects.

Added make docs-live target to the root project Makefile. This starts a live http server which refreshes with docs changes.
Added sphinx-autobuild to documentation requirements.
Added autodoc configuration to generate documentation from classes automatically.
API documentation attributes and parameters for core graphene objects and interfaces.
General tidying and documentation.
Fixed a flakey test involving datetime.now() by setting static values for times in tests.

changeling · 2019-05-25T21:44:47Z

I've been building a list of issues and suggestions for the docs over the last little while, and in a few PRs, you've managed to address most of them, at least as a very solid foundation. Kudos! One of the biggest was the lack of an fundamental autodoc style API reference. Much needed! Thank you!

Here's hoping that bit, at the very least, is adopted ASAP.

dvndrsn · 2019-05-25T21:58:13Z

@changeling thanks! please contribute some suggestions for documentation in this issue: #925

I'm hoping that with a good base document we can soon prioritize things into small chunks that more folks can contribute and polish it up nicely.

changeling · 2019-05-25T22:32:32Z

@dvndrsn, will do. I've been away for a week(-ish) in real life, so lemme go through my notes to catch back up. I've begun basic FAQs in the graphene and graphene-django wikis, in hopes folks might contribute recipes and pain-points, and to serve as a harvesting area for documentation development, but have only offered a couple of bits there before life happened. :)

I'd like to be more involved in the docs development going forward, and will look at my notes to see what, if anything, you've not already addressed in your PRs.

jkimbo

This is fantastic! I've added some (quite nitpicky) comments but overall this is so great.

graphene/types/argument.py

graphene/types/field.py

graphene/types/inputfield.py

graphene/types/union.py

graphene/types/mutation.py

dvndrsn · 2019-06-04T12:10:34Z

Thanks for the feedback @jkimbo! I accepted your suggestions and replied to your comment.

changeling

Looks good, though mebbe run black on the docstings code snippets.

changeling · 2019-06-04T22:54:53Z

graphene/types/argument.py

+
+    .. code:: python
+
+        age = graphene.String(


Might want to run black on code snippets in docstrings here.

age = graphene.String( # Boolean implicitly mounted as Argument dog_years=graphene.Boolean(description="convert to dog years"), # Boolean explicitly mounted as Argument decades=graphene.Argument(graphene.Boolean, default_value=False), )

Should I omit graphene.<Whatever> like you did in your PR?

I'd vote yes on this.

Yes from me too

Co-Authored-By: Jonathan Kim <[email protected]>

jkimbo

Some more suggestions (dropping the graphene in places) just for you to easily accept them. Happy to see this merged whenever you want though.

jkimbo · 2019-06-05T02:41:37Z

graphene/types/enum.py

+
+    .. code:: python
+
+        class NameFormat(graphene.Enum):


Suggested change

class NameFormat(graphene.Enum):

class NameFormat(Enum):

I think it's better to keep graphene to show exactly which Enum we mean.

This may be worth a larger conversation. Naming collisions with python modules like enum.Enum, for example. Perhaps a naming protocol going forward?

As @ProjectCheshire pointed out in https://graphenetools.slack.com/archives/CGR4VCHUL/p1559524808014100, core-next has these types available as, for example:

from graphql import ( GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)

See https://graphql-core-next.readthedocs.io/en/latest/intro.html#getting-started

I'll keep the import close in all examples to avoid confusion.

Agree with @phalt that the clash for name Enum is a little confusing. I do prefer the shorter names in code as these objects are used very often in the schema. GraphQL as a prefix seems like overkill in most cases (especially given the namespace graphql and graphene for the module).

jkimbo · 2019-06-05T02:42:08Z

graphene/types/inputobjecttype.py

+
+    .. code:: python
+
+        class Person(graphene.InputObjectType):


Suggested change

class Person(graphene.InputObjectType):

class Person(InputObjectType):

jkimbo · 2019-06-05T02:42:16Z

graphene/types/interface.py

+
+    .. code:: python
+
+        class HasAddress(graphene.Interface):


Suggested change

class HasAddress(graphene.Interface):

class HasAddress(Interface):

jkimbo · 2019-06-05T02:42:25Z

graphene/types/mutation.py

+
+    .. code:: python
+
+        class CreatePerson(graphene.Mutation):


Suggested change

class CreatePerson(graphene.Mutation):

class CreatePerson(Mutation):

jkimbo · 2019-06-05T02:42:43Z

graphene/types/union.py

+
+    .. code:: python
+
+        class SearchResult(graphene.Union):


Suggested change

class SearchResult(graphene.Union):

class SearchResult(Union):

phalt

This is an awesome effort well done! Few minor points and please pin the version in requirements.

phalt · 2019-06-05T09:10:35Z

docs/requirements.txt

@@ -1,4 +1,5 @@
 # Required library
 Sphinx==1.5.3
+sphinx-autobuild


please pin this to a specific version

phalt · 2019-06-05T09:11:52Z

graphene/types/enum.py

+
+    .. code:: python
+
+        class NameFormat(graphene.Enum):


I think it's better to keep graphene to show exactly which Enum we mean.

graphene/types/json.py

dvndrsn · 2019-06-05T22:07:26Z

I'm going to try to get to these comments by the weekend so this can be merged. Lil crazy this week.

changeling · 2019-06-08T22:28:56Z

graphene/types/enum.py

@@ -67,6 +67,28 @@ def from_enum(cls, enum, description=None, deprecation_reason=None):  # noqa: N8


 class Enum(six.with_metaclass(EnumMeta, UnmountedType, BaseType)):
+    """
+    Enum type defintion


Suggested change

Enum type defintion

Enum type definition

changeling · 2019-06-08T22:39:02Z

graphene/types/argument.py

+            dog_years=graphene.Boolean(description='convert to dog years'),
+            # Boolean explicitly mounted as Argument
+            decades=graphene.Argument(graphene.Boolean, default_value=False)
+        )


Suggested change

)

age = String(

# Boolean implicitly mounted as Argument

dog_years=Boolean(description="convert to dog years"),

# Boolean explicitly mounted as Argument

decades=Argument(Boolean, default_value=False),

)

Addressed comments in docs and pinning dependencies.

dvndrsn · 2019-06-09T13:55:29Z

@jkimbo @ekampf @ProjectCheshire - this is ready to merge now.

dvndrsn changed the title ~~expose livehtml autobuild in Makefile~~ expose livehtml autobuild in Makefile + Add API autodoc May 25, 2019

dvndrsn mentioned this pull request May 25, 2019

Low-resolution documentation and its solution #925

Closed

changeling mentioned this pull request May 25, 2019

Add autodoc-style API reference. graphql-python/graphene-django#650

Closed

ProjectCheshire approved these changes May 29, 2019

View reviewed changes

jkimbo requested changes Jun 3, 2019

View reviewed changes

changeling added the 📖 documentation label Jun 4, 2019

dvndrsn requested review from changeling and phalt as code owners June 4, 2019 21:50

changeling approved these changes Jun 4, 2019

View reviewed changes

dvndrsn and others added 10 commits June 4, 2019 19:00

expose livehtml autobuild in Makefile

7384614

add API documentation for schema

79f8470

document graphene core API

882d18e

fixes black lint

1184f07

Update graphene/types/union.py

07b87c5

Co-Authored-By: Jonathan Kim <[email protected]>

Update graphene/types/argument.py

f8a6aa2

Co-Authored-By: Jonathan Kim <[email protected]>

Update graphene/types/field.py

2b01a8e

Co-Authored-By: Jonathan Kim <[email protected]>

Update graphene/types/inputfield.py

0bd4d93

Co-Authored-By: Jonathan Kim <[email protected]>

add note about non-functional interfaces meta argument in mutation

e141e43

update with other virtual environment configuration

67f6976

dvndrsn force-pushed the expose-docs-commands-in-makefile branch from 947c00c to 67f6976 Compare June 4, 2019 23:35

dvndrsn mentioned this pull request Jun 4, 2019

Mutation argument interfaces does not work #994

Closed

jkimbo approved these changes Jun 5, 2019

View reviewed changes

phalt previously requested changes Jun 5, 2019

View reviewed changes

changeling reviewed Jun 8, 2019

View reviewed changes

dvndrsn added 5 commits June 9, 2019 08:50

pin autobuild

17e57e7

format argument example code

42bfb37

format enum input object and interface examples

e761d25

format enum mutation union examples

37d32de

revise documentation with imports, capitalization

125ef51

dvndrsn requested a review from phalt June 9, 2019 13:52

jkimbo merged commit da1359e into graphql-python:master Jun 9, 2019

This was referenced Jun 11, 2019

v2.1.6 #1005

Merged

Add API documentation graphql-python/graphene-django#679

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

expose livehtml autobuild in Makefile + Add API autodoc #971

expose livehtml autobuild in Makefile + Add API autodoc #971

dvndrsn commented May 22, 2019 •

edited

Loading

changeling commented May 25, 2019 •

edited

Loading

dvndrsn commented May 25, 2019

changeling commented May 25, 2019

jkimbo left a comment

dvndrsn commented Jun 4, 2019

changeling left a comment

changeling Jun 4, 2019

changeling Jun 4, 2019

dvndrsn Jun 4, 2019

changeling Jun 5, 2019

jkimbo Jun 5, 2019

jkimbo left a comment

jkimbo Jun 5, 2019

phalt Jun 5, 2019

changeling Jun 7, 2019

dvndrsn Jun 9, 2019

jkimbo Jun 5, 2019

jkimbo Jun 5, 2019

jkimbo Jun 5, 2019

jkimbo Jun 5, 2019

phalt left a comment

phalt Jun 5, 2019

phalt Jun 5, 2019

dvndrsn commented Jun 5, 2019

changeling Jun 8, 2019

changeling Jun 8, 2019

dvndrsn commented Jun 9, 2019

	class Person(graphene.InputObjectType):
	class Person(InputObjectType):

	class HasAddress(graphene.Interface):
	class HasAddress(Interface):

	class CreatePerson(graphene.Mutation):
	class CreatePerson(Mutation):

	class SearchResult(graphene.Union):
	class SearchResult(Union):

-        )
+        age = String(
+                # Boolean implicitly mounted as Argument
+                dog_years=Boolean(description="convert to dog years"),
+                # Boolean explicitly mounted as Argument
+                decades=Argument(Boolean, default_value=False),
+        )

expose livehtml autobuild in Makefile + Add API autodoc #971

expose livehtml autobuild in Makefile + Add API autodoc #971

Conversation

dvndrsn commented May 22, 2019 • edited Loading

changeling commented May 25, 2019 • edited Loading

dvndrsn commented May 25, 2019

changeling commented May 25, 2019

jkimbo left a comment

Choose a reason for hiding this comment

dvndrsn commented Jun 4, 2019

changeling left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jkimbo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

phalt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dvndrsn commented Jun 5, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dvndrsn commented Jun 9, 2019

dvndrsn commented May 22, 2019 •

edited

Loading

changeling commented May 25, 2019 •

edited

Loading