Skip to content

Include a functional example in GraphQL docs

What does this MR do?

Intent: Set up a functional template to help our readers actually use our GraphQL implementation to get data. To do so:

  • Set up dedicated pages for each example (sometimes known as a "use case")
  • Start each new page with an explanation
    • Include each new page in the doc/api/graphql directory
  • Include a "working" GraphQL code block that can be copied to the GraphiQL Explorer
    • Include graphql as a label for the code block
  • Include a screenshot of the GraphiQL explorer, with the YAML example and output, so readers know what to expect
    • Include each screenshot in the doc/api/graphql/img directory
  • Set up the docs.gitlab.com/ee ToC to include the title of each dedicated page, "side by side" with the GraphQL reference
  • Refer to the reference page for properties/attributes. Given the principles of SSoT, it should not be necessary to define any attributes on the dedicated example page

If approved, the logical follow-up would be to set up an MR template dedicated to GraphQL examples.

The functional doc example included in this MR is based on the linked issue, ref: #215661

I set up this template based on GitLab Contribute 2020 discussions.

Screenshot_from_2020-07-02_13-59-59

Related issues

Author's checklist (required)

When applicable:

Review checklist

All reviewers can help ensure accuracy, clarity, completeness, and adherence to the Documentation Guidelines and Style Guide.

1. Primary Reviewer

  • Review by a code reviewer or other selected colleague to confirm accuracy, clarity, and completeness. This can be skipped for minor fixes without substantive content changes.

2. Technical Writer

  • Optional: Technical writer review. If not requested for this MR, must be scheduled post-merge. To request for this MR, assign the writer listed for the applicable DevOps stage.

3. Maintainer

  1. Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.
  2. Ensure a release milestone is set.
  3. If there has not been a technical writer review, create an issue for one using the Doc Review template.
Edited by Mike Jang

Merge request reports