Create code samples from code, a.k.a. code excerpts

[ahmednfwela]

Pull Request

What does this PR do?

This PR completely automates updating the code samples file .code-samples.meilisearch.yaml
it creates a new PRIVATE tool that does 2 things

1. updates the sample file from source code (run by contributors)
2. check if the sample file is up to date with source code (run in CI)

the private tool checks dart files in lib/ and test/ directory for lines that follow this pattern:

// #docregion key
anything()
// #enddocregion

where key is a key in .code-samples.meilisearch.yaml

This run shows CI fail in action, due to format mismatch for key search_parameter_guide_show_ranking_score_1 between code file and yaml file.

This commit f9109a0 shows how to fix the failed run, by running dart run ./tool/bin/meili.dart update-samples in the root directory of the repo.

this should simplify adding samples, and avoid issues like #357

---

Update

I have also added functionality to detect missing and useless keys, see this failing run for example: https://github.com/meilisearch/meilisearch-dart/actions/runs/6262599763/job/17005143489?pr=358#step:4:159

PR checklist

WIP

• remove unnecessary indentations from code.
  Please check if your PR fulfills the following requirements:
• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (bf1f5d4) 82.03% compared to head (228a95b) 82.03%.
Report is 28 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #358   +/-   ##
=======================================
  Coverage   82.03%   82.03%           
=======================================
  Files          57       57           
  Lines        1353     1353           
=======================================
  Hits         1110     1110           
  Misses        243      243           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[ahmednfwela]

@curquiza @brunoocasali the internal tool still needs more work, but I want your opinion if you agree with this approach.

[brunoocasali]

I'm very sorry @ahmednfwela for taking so long here 😢

That's very cool @ahmednfwela let's go for it! Do you think it would be possible to do that with other languages but using the same tooling?

Also, can you update the CONTRIBUTING?

[ahmednfwela]

@brunoocasali Yes we can definitely do that with any language that supports comments, the tooling is language agnostic.

we can ship the tooling as an exe file that's built from a different repository

[brunoocasali]

LGTM!

[brunoocasali]

LGTM

[ahmednfwela]

bors merge

[meili-bors]

Build succeeded:

• integration-tests (dart 3.0.0)
• linter-check
• pana