Contributing

Thanks for considering making a contribution! Every issue or question helps!

This package uses melos to manage dependencies. To install it run:

pub global activate melos

Then, to link the local packages run:

melos bootstrap

If using fvm, you may need to run:

fvm flutter pub global run melos bootstrap

You can view most of the commands that you will need in the melos.yaml file. However, melos can be used to do other stuff like executing any command you want using melos exec, for more information please view the melos Github repo.

Scripts

The following scripts are used in CI and can be used thought development. At the moment, both of them are related to generating documentation.

collect_examples.dart

This script allows you to include documentation in the README files (or any Markdown file) from comments in Dart code. In the future, we will probably support sharing documentation between Dart files.

For example, by placing this comment annotations in a section of a Dart file:

// @example-start{name-of-example,extension:graphql,start:1,end:-2}
const graphQLTypeSection = '''
type ObjectName {
  objectField: String
}
''';
// @example-end{name-of-example}

And adding this comment in the Markdown (.md) file:

<!-- include{name-of-example} -->

You can copy the same Dart snippet by executing dart run script/collect_examples.dart. The Markdown file will be updated to:

<!-- include{name-of-example} -->
```graphql
type ObjectName {
  objectField: String
}
```
<!-- include-end{name-of-example} -->

You can find many examples in the source code of this README with Dart examples annotated through out the repository's Dart files.

The scripts has a couple of arguments, in particular --check is used in CI to verify the the code snippets are synchronized between the Dart files and Markdown files. --generate-dart-file will generate Dart code with the snippet Strings and --generate-md-dir will generate one .md file for each example within the directory passed as argument.

generate_docusaurus.dart

Generates the Docusaurus documentation page. Basically, it copies the README file sections into the /docusaurus/docs/ directory in a format that Docusaurus understands. This is used in CI to build the documentation page.

Small pieces of configuration can be included within the README files. For example, to assign tags to a section (which will be converted to a page, perhaps /docs/leto_shelf/section-title if it is in leto_shelf's README) you can use.

# Section Title <!-- docusaurus{"tags":["tagName1","tagName2"]} -->

The content with the brackets should be a JSON string.