search

dgraph-io / dgraph-docs

A native GraphQL Database with a graph backend
https://dgraph.io/docs
Other
35 stars 66 forks source link

readme

Dgraph Documentation

To read the official Dgraph documentation that is published from this repository, please see https://dgraph.io/docs/.

Contribution guidelines

As a contributor to Dgraph documentation, we ask that you do the following:

Technical writing style

Dgraph Labs uses a style guide for our documentation so that we can make it as easy to understand as possible. The Dgraph Style Guide is a concise style reference for our documentation, but it isn't comprehensive. For anything not found in our style guide, use Google's Developer Docs Style Guide.

Style tips for machine-translatable docs!

Making our documentation easy to understand includes optimizing it for client-side machine translation into other languages. To help with this, please see the following technical writing style tips:

Note: Please don't let these style conventions stop you from creating a PR to share your contribution to Dgraph Docs! PR reviewers can help with style guide issues.

references

Use hugo shortcode for relref.

Example, to reference a term, use a relref to the glossary :

>  [entity]({{< relref "dgraph-glossary.md#entity" >}})

Staging doc updates locally

We use Hugo for our documentation. You can use Hugo to locally stage doc updates before or after creating a PR.

  1. Download and install hugo version v0.91 from here.

  2. Run the command below to get the theme.

    pushd themes && git clone https://github.com/dgraph-io/hugo-docs && popd

  3. Run ./scripts/local.sh and visit http://localhost:1313 to see the documentation site running on your local machine.

(Optional) To run queries within the documentation using a different Dgraph instance, set the DGRAPH_ENDPOINT environment variable before starting the local web server:

DGRAPH_ENDPOINT="http://localhost:8080/query?latency=true" ./scripts/local.sh

Now you can make changes to the docs and see them being updated instantly, thanks to Hugo.

Note: While running locally, the version selector does not work because you need to build the documentation and serve it behind a reverse proxy to have multiple versions. Also, formatting of lists is less fussy when running locally; so please precede lists with a blank line in your PR.

Running docs locally with Docker

Make sure you have docker-compose installed.

Run:

sh scripts/docker.sh

Branch

Depending on what branch you are on, some code examples will dynamically change. For example, go-grpc code examples will have different import path depending on the branch name.

Runnable code examples

Some code examples are runnable, allowing for reader interaction with a data set.

Custom example

Pass custom Go-GRPC example to the runnable by passing a customExampleGoGRPC to the runnable shortcode.

{{< runnable
  customExampleGoGRPC="this\nis\nan example"
>}}{
  director(func:allofterms(name, "steven spielberg")) {
    name@en
    director.film (orderdesc: initial_release_date) {
      name@en
      initial_release_date
    }
  }
}
{{< /runnable >}}

Note: Runnable doesn't support passing a multiline string as an argument to a shortcode. Therefore, you have to create the whole custom example in a single line string by replacing newlines with \n.

History

add Hypermode banner by updating the hugo-docs repository with topbat template.