Laerning Tool

Introduction

Laerning Tool is an API that provides access to learning environments for flash-card style questions. This is useful for various scenarios

Obvious uses:

• learning languages

• learning topics (such as electro dynamics)

• learning maps

• learning geo-policital statistics

• learning historic events

Non-obvious uses:

• learning rules to a complex game

• learning a style of writing

• fun quizzes (trivia, jackbox-esque, made up stuff)

• reinforcing process or exercises ("how to build and deploy this project", "how to remember the flow of thought for a presentation")

• reinforcing the key points from books you read

There are many more. Any time you would have said "ah, I should put some effort into getting better at this!", this software should be the answer. The datasets should be available online so others can use the data created!

More info can be found on the Wiki.

OpenAPI specification

There is an OpenAPI specification and associated SwaggerUI interface to get to grips with the engine easier.

You can access an interactive API via the normal /swagger-ui path.

I also have a hosted site where you should be able to play around with the latest release.

The spec itself is available at the /api-docs/openapi.json path, if you are generating clients for this engine.

XML Format

The learning modules (dataset) are a custom format that complies with XML standard. There is an XML Schema Definition declared in laerning-module.xsd. You can link it at the top of your XML files (like the ones in data/) to have it checked for correctness in your editor.

Diagrams

There are some helpful diagrams in the repository. They have the extension .graphml and can be opened with yEd graph editor.

Roadmap

The roadmap is better described in individual milestones.

Labels and contributing

Contributions are very much welcome and encouraged! I will definitely try as much as possible to help people add to this project.

Below is an explanation of the labels used in the issues tab. You should be able to use these to find tickets you would like to pick up.

Dataset issues are related to xml files located under 'data' directory only. Some may be about introducing new datasets. Others may be about improving existing ones.

Bug issues are for tracking flaws in existing functionality.

Enhancement issues are for tracking features. These tend to be bigger, but not always.

Good first issue tickets are a great entry point if you are new to contributing or otherwise want something easier to do.

Help wanted issues are tickets that I would like, but am almost convinced I do not have the capacity to do them myself. These tend to be great to pick up as they may have minimal impact on the main work happening, and can be worked on independently.

Refactor tickets are all about changing the code without breaking anything. This will be necessary to maintain a nice codebase. The tickets can be fun if you would like to get familiar with a specific technology or way of doing things in rust.

Triage issues are new issues that I haven’t looked at yet. It means I have yet to review and categorise them properly.

Frequently Asked Questions

How do I run/test/build from source

This is a standard cargo project. You can run the standard commands.

cargo run
cargo test
cargo build --release
RUST_LOG=laerning_tool=trace,surrealdb=debug cargo run

The project also supports CLI commands. You can run them

./target/debug/laerning-tool-api [COMMAND]

Here’s an example:

./target/debug/laerning-tool-api -h
This is a software project to help people make flash cards to test themselves on things they want to learn.

Usage: laerning-tool-api [OPTIONS]

Options:
  -b, --bind <BIND>                Socket address on which the server will listen
      --db-location <DB_LOCATION>  SurrealDB Storage Location. Should be in URI format (ie file://)
      --directory <DIRECTORY>      Dataset Directory location
  -h, --help                       Print help
  -V, --version                    Print version
  ```

You can find pre-made releases in the https://github.com/phughk/laerning-tool/releases[releases tab] to the right of the GitHub page.

=== How do I run the binary on Mac

sudo spctl --master-disable ./laerning-tool sudo spctl --master-enable

Be careful with what you run from the internet;
The above disables your Mac's security temporarily to bypass safety checks.