How to write docs pages

Purpose

This page explains how to write docs pages so that we have a consistent structure across our whole documentation.

Docs page structure

Meta information

The following meta information should be added at the beginning of each docs page: description and keywords.

An example:

.. meta::
   :description: Data validations in Hasura
   :keywords: hasura, docs, schema, data validation

Reference

Before the page title, add a reference that can be used to link to this page.

An example:

.. _data_validations:

Note: References can also be added above any title within the docs page in order to link to a specific section directly.

Page title

Add a main title for each docs page.

An example:

Data validations
================

Table of contents

Add a table of contents.

.. contents:: Table of contents
  :backlinks: none
  :depth: 2
  :local:

Introduction

Add an Introduction section:

Introduction
------------

In the section, give a short overview of what the page is about.

General guidelines

Headings

• Ensure heading underlines are the same length as the headings. Short underlines will throw warnings during builds.
• Use bold in headings in place of string literals for aesthetics (i.e. ** in place of ``).
• The nesting of headings is as follows:

Main page title
===============

First heading
-------------

Second heading
^^^^^^^^^^^^^^

Third heading
"""""""""""""

Fourth heading
**************

References / links

Internal links

When linking to other docs pages, use references (:ref:) rather than relative links in order to avoid broken links.

An example:

:ref:`data validation <data_validation>`

In this example, data validation is the link text, and <data_validation> is the reference to which the link will point.

External links

When linking to external pages, make sure to add a double _ in the end to avoid Duplicate explicit target name warnings.

An example:

Google <https://www.google.com/>__

Note: If you link to an external resource, make sure to link to the most current version of the same, e.g. https://www.postgresql.org/docs/current/intro-whatis.html rather than https://www.postgresql.org/docs/9.6/intro-whatis.html.

Images

Before adding images to docs, first compress them via some tool to ensure users don't have to unnecessarily download more data than needed. You can use www.tinypng.com (tinypng-cli) for this. Sometimes you can compress images by over 75% without losing any visible quality.

Add images using the thumbnail directive to allow click-to-zoom.

An example:

.. thumbnail:: /img/graphql/manual/schema/validation-add-check-constraint.png
   :alt: Add check constraint
   :width: 700px

• Add an :alt: tag for all images
• To adjust the image size, use the :width: tag

Notes / Admonitions

A note can be added in order to draw attention to something like limitations, or to link to external reference documentation. It has the title "Notes".

An example:

.. note::
  Please checkout the [Postgres documentation](https://www.postgresql.org/docs/current/functions-comparison.html) for more information.

An admonition is the same as a note, but its title can be defined.

Add an admonition as follows:

.. admonition:: Supported from
  Scheduled triggers are supported from `v.1.3.0` and above.

Note: Make sure to place the note / admonition in a place where the user will see it at the appropriate time.

GraphiQL

Our docs have a GraphiQL extension that allows displaying GraphQL requests in the GraphiQL UI.

Use it as follows:

.. graphiql::
  :view_only:
  :query:
    query {
      author_by_pk(id: 1) {
        id
        name
      }
    }
  :response:
    {
      "data": {
        "author_by_pk": {
          "id": 1,
          "name": "Justin"
        }
      }
    }

Code blocks

While adding code blocks ensure the right language type is set. Sometimes adding placeholders breaks the language's syntax in which case you'll have to set the language type to none to avoid warnings during builds.

GraphQL request examples

While adding GraphQL request examples:

• Use a tab width of 2 for nesting the requests and responses for optimal use of the space and maintaining consistency.
• Nest query arguments for logical readability. Unfortunately GraphiQL prettify does not do a good job of doing this by default.
• Ensure that the order of fields in the responses is the same as in the requests for better readability.