search

graphql-python / graphene

GraphQL framework for Python
http://graphene-python.org/
MIT License
8.06k stars 823 forks source link

Improve Docs #823

Closed syrusakbary closed 5 years ago

syrusakbary commented 6 years ago

This issue aims to track different documentation issues within Graphene / GraphQL Python ecosystem. One simple search in the Github issues will help for that: https://github.com/graphql-python/graphene/issues?q=is%3Aissue+is%3Aopen+docs+label%3A%22%F0%9F%93%96+documentation%22

Main goals:

Any more ideas?

dani0805 commented 6 years ago

best practices to avoid performance bottlenecks and n+1 problems

helloqiu commented 5 years ago

It would be great if some documents about how to change a schema name (#839) can be added.

genericmoniker commented 5 years ago

Why is the "Mutations" section under "Types Reference"? It seems like it would fit better in an operation type section, so that queries and mutations are together.

Add more GraphQL examples showing how a particular Python construct is used.

Add explanations of why something would be useful. "You can pass context to a query via context." OK...

Some sections are a bit awkward, and could use general editing:

lggwettmann commented 5 years ago

Same with the graphene-django documentation. I have quite some problems trying to make it work and the documentation is seriously lacking lots of deeper info.

antoine-gallix commented 5 years ago

I'm starting to use graphene at our company to replace our REST API. I feel slowed down by the fact that the documentation is only composed of a tutorial. In my opinion, a good documentation is composed of a verbose tutorial to get people started on the basic concept, and a more terse but complete API reference where users can lookup details, signatures, parameters definitions and expected behaviors. Also in the case of a framework, explain the workflow that the framework is following. Which user function is called in which order for example. The most common approach in big python packages seems to be that the API reference, that is closer to the code, is self generated from the docstrings in the code itself. I had to often dive into the package source code to find answers to my questions and I felt a bit lost with the lack of docstrings and comments in the code as well. And just as a note, I would be willing to contribute a bit to the documentation.

dvndrsn commented 5 years ago

I'd also be interested in contributing to documentation. I've been using Graphene for over a year now and we've done our share of digging through the code to reverse engineer solutions and discover best practices for ourselves.

Just wondering what the best place to start is though!

ProjectCheshire commented 5 years ago

Documentation is similar to a schema with models/types/mutations/queries scoped by 'entity'.

There are clear 'sections' within graphql-python which each need elements like

In general, I find lists help people focus and see the progress of a thing. It is easier to say "I will do a pull request to add a non-trivial example to the middleware section" vs 'Yay! I'd love to to help!" and be confronted with the vast blank paper (editor) problem of where to start, and also know what is already being worked on. E.g. I think the subscriptions/websocket area needs a hefty amount of docs given the issues I see come through here and elsewhere - I use RabbitMQ for my pubsub support (since I'm already using it for RPC support), it's worked great, but I have no idea of better practices or what others are doing.

My wishlist:

Similar to the integrations, I'd love to see an Appendix where the community can submit supplementary libraries that integrate with graphql-python.

Not being an armchair pontificator witout action, I can take a first stab at an outline if the general breakdown of what is wanted for each section seems accurate / other additions. @syrusakbary thoughts?

jkimbo commented 5 years ago

@ProjectCheshire great comment and I would be very interested to see what you think an outline for the docs would look like.

Just so you're aware though there is currently quite a bit of uncertainty with the maintenance of this project (see https://github.com/graphql-python/graphene/issues/884#issuecomment-456995174) and the community is waiting on @syrusakbary to provide a clear plan going forward. Until then it's unclear how anything (like the website) gets updated so any contributions might take a while to be accepted.

ProjectCheshire commented 5 years ago

@jkimbo yikes. Thanks for the headsup.

I think it's a feedback loop - the better the docs, the easier it is to grow a community which in turn begets better docs/contributions and better utilization in production environments (which gets better press and thus more community so on so forth).

( Related to the above, I think it'd be grand to have 'starter kits' where someone could clone a repo and get at least a semi-functional app they can poke with basic things like auth, subscriptions, etc. so they can build on that vs everything from scratch - good for growth and new blood - there may very well be some, just not well advertised)

timsavage commented 5 years ago

Documentation of generating errors in mutations would be nice. Searching in the documentation for GraphQLError returns no results.

changeling commented 5 years ago

I've posted a couple of issues here: https://github.com/graphql-python/graphene-django/issues/632

Is this thread still intended "to track different documentation issues within Graphene / GraphQL Python ecosystem"?

It might be a good idea to: a) Pin this post b) have an equivalent post within each project to encourage both discovery and PR submissions.

Another suggestion: This seems like a good opportunity to get the project wikis going with best practices, and collecting snippet examples of common how-do-I questions. That offers a much more rapid turn-around and easier, and broader, (in the sense that folks not comfortable creating PRs can contribute), path to collecting common solutions and FAQ style issues.

In the short term, I'd suggest prioritizing the clean-up of docs to ensure they are at least accurate as they stand. I suspect a lot of newbies are being frustrated and lost to the graphene-* community because the documentation simply isn't accurate or entirely functional. Personally, I've lost hours trying to figure out where I went wrong only to ultimately discover the documented behavior or example was at fault.

changeling commented 5 years ago

Just bumping my above question. Should this issue continue to be used to track Documentation issues, or should https://github.com/graphql-python/graphene/issues/925 be used? IMHO, one of the challenges right now for adopters is that there are consistency lapses in the docs as well as in the appropriate places for discussion and tracking. It seems like establishing a clear structure would make a tremendous difference for folks just coming in, as well as for folks maintaining and supporting.

On another note, at this point some of the docs just simply are incorrect and lead to frustration when users attempt to follow the examples. I think a first step would be a coodinated effort to walk through the docs, as if just learning, and simply do exactly as they say, identifying non-functional and inconsistent elements.

A clean experience following the tutorials would go a long, long way towards increasing adoption.

Having a single entry point, probably in the README, identifying what and where things exist, and which elements of the ecosystem are current and integrated, and which aren't really relevant to beginners, likewise, would be a great resource.

changeling commented 5 years ago

Here's an early post from @syrusakbary that has some good discussion as we go forward devloping the docs. For one, is @staticmethod necessary in the examples.

https://github.com/graphql-python/graphene/issues/612

jkimbo commented 5 years ago

@changeling that has come up recently and the consensus was that we shouldn't add @staticmethod to all resolvers in the documentation: https://github.com/graphql-python/graphene/pull/952#issuecomment-488208292

changeling commented 5 years ago

@jkimbo So glad to hear that. Thanks. Putting together a (rough) collection of these for a style guide on the wiki. Any others that come to mind?

stale[bot] commented 5 years ago

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

sfbaker7 commented 4 years ago

Hey, newcomer to both graphql and graphene here (hoping my perspective will provide helpful feedback). As mentioned in #925, I find that the documentation is still a bit terse.

Specifically, I feel like there is a gap between simply defining the concept and trying to understand how the developer will end up using or needing said concept. For example, the section on lists gives a very basic example of creating a list of strings and moves on. As a developer, I know I'm going to be using lists all the time (how often does the frontend only ask for one of something? ), and most likely, I would want to be returning a list of other objects. I would assume with a high probability this is true for almost all web-developers. So going into the documentation, I had a number of questions in my head: What's the best way to return other objects in my resolver function? How much does the parent object need to know about the child object? What if an object is returning a list of itself (user returning users). The example provided covered the most basic base-case and moved on.

Although most questions are answerable with some digging, the solution I end up going with has huge design ramifications, so I would prefer to know from the start what the best approach is that I can have a higher degree of confidence when making decisions.

jkimbo commented 4 years ago

Thanks for the feedback @sfbaker7 and I totally agree with you. Unfortunately after having worked with Graphene for multiple years now I don't see the lack of information anymore so it's always helpful to have fresh eyes. I will create an issue to improve the documentation around List which is lacking as you've pointed out. If there are other parts of the documentation that you found sparse then please create new issues for those as well.

jkimbo commented 4 years ago

Issue created for list documentation: https://github.com/graphql-python/graphene/issues/1171