Not only does it take a bit to load this page, it's difficult to search in page because of how large it is. Compared to other pages it seems to perform not so great.
Proposal
Could we consider breaking down the GraphQL reference docs or consider other methods of loading in all the different references?
Who can address the issue
While this isn't strictly documentation, this has to do with docs.gitlab.com performance with a specific page. I'm not 100% sure who owns this.
@.luke Thank you, I agree. That's a massive page We could simply move each level 2 heading (##) to its own child page and break up Abstract types into Unions and Interfaces so that we have this structure:
Looking at our current method of generating docs, I think we should drop the graphql-docs gem and write our own bespoke code to generate the docs.
This isn't because the graphql-docs gem is bad, but just because:
We hardly use any of it. We only use the parser of the graphql-docs gem but nothing else. The parser is a relatively simple class that transforms the schema to a large Hash.
We don't actually want that hash. We do backflips in our rendering of the docs to map back from the Hash we receive to the schema objects in order to access more data than what is presented in the Hash. For example:
We have a #schema_field method to return the real field object to access the "doc reference".
The parser isn't written in a way where we can subclass and override parts of it, or extend it.
The graphql-docs gem by default renders the parsed schema into a number of pages like queries, mutations, input objects, directives, etc. But we don't use the gem's renderer because it outputs HTML and we want GitLab-Flavoured Markdown. Instead, we render the parsed schema into our own template.
Given we only use the graphql-docs gem for its parsing of the schema, and we have a lot of complex code trying to access more data from the parsed Hash we receive, I think we should just parse the schema ourselves and drop the gem.
1
Luke Duncalfechanged title from GraphQL Reference Page is Slow to GraphQL Reference page should be split into sections
changed title from GraphQL Reference Page is Slow to GraphQL Reference page should be split into sections
There's a work in progress !130378 which is ~70% complete. The next steps would be to have some eyes on the progress then start chunking the work into smaller bits, write more tests, and have them reviewed. I'll be OoO until 1 April, but will happily start this process when I return unless someone wishes to pick it up earlier .
@wortschi Yes, you've got it. It's a large MR already. In my mind, the steps would be to split that WIP into MRs, finishing the work for each slice (it's unfinished and lacking in tests):
First the "core" part: The rake task and the classes that are called by that rake task. In this MR either the bare minimum of actual docs pages would be generated, or none at all for this iteration. For this, I was imagining choosing @engwan as an initial reviewer who has familiarity with GraphQL but I thought would be well suited to scrutinising the code.
Then we start adding the different GraphQL types, which are the Tooling::Graphql::ExperimentalDocs::Schema parts of the MR. We'd add tests for how the generated docs look, and ensure that we're generating with parity of the existing docs (but improving them too!). This current WIP MR has only implemented a subset of these types.
We'd keep going until those docs were able to generate all GraphQL types, and we (TWs, engineers, perhaps designers?) were happy with the generated docs, we'd then take a step to "make them live" by:
Have the new docs be generated at the same location as the old docs
Deprecate the existing gitlab:graphql:compile_docs task and have it call a new gitlab:graphql:compile:docs task, and ensure the graphql-verify pipeline check works fine.
I'll give the remainder work a guess-weight of 5. There's a bit of uncertainty about that though, given the amount of time since I looked at that WIP MR.