Create and fill sample file to display Python examples in MeiliSearch Documentation

Code Samples for MeiliSearch documentation

Introduction

As MeiliSearch grows so does its SDK’s. More and more SDK’s rises from the ground and they all deserve to be as well documented as the core engine itself.

The most common way for a user to understand MeiliSearch is to go to its official documentation. As of yesterday all examples in the documentation were made with cURL. Unfortunately, most of our users do not communicate with MeiliSearch directly with cURL. Which forces them to search for the specific references somewhere else (in the readme’s, in the sdk’s code itself,…). This makes for unnecessary friction.

Goal

We want our documentation to include all SDK’s

As a first step we want all examples to be made using the most possible SDK’s. As did Stripe and Algolia.

examples with curl and javascript SDK and soon enough this SDK too!

To achieve this it is expected from this SDK to create a sample file containing all the code samples needed by the documentation.

These are the steps to follow:

• Create your sample file
• Fill your sample file
• Add your samples to the documentation

Create your sample file

The sample file is a yaml file added at the root of each MeiliSearch SDK. Sample files are created based on the sample-template.yaml file.

sample-template file:

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

This template is accessible publicly here or in the public directory : .vuepress/public/sample-template.yaml of the documentation.

The name of the file should be .code-samples.meilisearch.yaml

Fill your sample file

After creating the sample file with the content of the sample template you should have a file containing all the sampleId’s.

get_one_index_1: |-
list_all_indexes_1: |-
create_an_index_1: |-
...

By the name of the different sampleId you should know where that code sample will be added to the documentation.

For example, create_an_index_1 is the first example in the API References of the index creation.

Using the already existing cURL example in the documentation you should see what is expected from that sample. It is very important that you look at the already existing samples in the documentation as it gives you the parameters to use in your sample to match with the rest of the documentation.

Good sample based on documentation:

create_an_index_1: |-
  client.createIndex({ uid: 'movies' })

Bad sample that does not match with the response.

create_an_index_1: |-
  client.createIndex({ uid: 'otherName' })

Each sample is expected to be written in the respective SDK language.

Javascript example:

get_one_index_1: |-
  client.getIndex('movies').show()
list_all_indexes_1: |-
  client.listIndexes()
create_an_index_1: |-
  client.createIndex({ uid: 'movies' })
  ...

The complete cURL sample file is available at the root of the documentation repository. Every other SDK sample file should be available at the root of their respective repository.

Formatting Exception

There is one exception to the formatting rule. When the sampleId finishes with _md it means it is expected to be written in markdown format.

JavaScript sample id with _md extension:

Add your samples to the documentation

Once your sample file is filled with the code samples, you will need to create a pull request on the documentation repository.

Open the following file in your IDE: .vuepress/code-samples/sdks.json

And add your sample file to the list:

[
  ...
  {
    "language": "sdk-language",
    "label": "sdk-label",
    "url": "url to yaml file"
  }
]

The language key expect a supported language for the code highlight.

The label key is the name of the tab. While label and language could have been the same, it created some conflict (i.e: bash and cURL).

The url is the raw link to access your sample file. It should look like this: https://raw.githubusercontent.com/[PROJECT]/[REPO]/.code-samples.meilisearch.yaml

[bidoubiwa]

I changed the link with @curquiza link. I forgot to add “https://” . This issue is still in WIP until I have merged the PR in the documentation repo

[eskombro]

@curquiza there was a hyperlinked text “here” leading to a 404 error 😃 Now it links to the actual file, thanks @bidoubiwa