Documentation sections

[mackode]

Let's say each comment around field and definitions is an entity. Is it possible to group those entities in some logical sections?

e.g. group documentation regarding Credentials in 1 sections and other data in another. So they are all not generated always in Queries/Mutations, but

-> Queries -> Credentials section
-> Mutation -> Credentials section

or

-> Credentials:
-> Queries
-> Mutations

[brettchalupa]

@mackode This makes sense to me. I think having one big alphabetical list can be challenging for viewing large APIs. I'd like to see this improved too.

A challenge here is how are sections defined? Since the docs are generated from the GQL schema, which is flat, it then becomes tricky for how to group sections together.

There's already sections for Queries, Mutations, Enums, Input Objects, etc. Maybe having collapsible sections would be helpful?

Let me know if you have any additional thoughts or ideas here!

[mackode]

At the time I asked I think I had a few ideas:

• One is using Namespace-types convention (https://graphql-rules.com/rules/mutation-namespaces)
• Some common prefixes convention, like Articles_list, Articles_like, then the there will be a Section called Articles

[brettchalupa]

@mackode thanks for sharing your thoughts and resources. I think organizing by the namespace would be helpful. Especially if that's a convention more and more people use. Will leave this open for consideration and feedback.