rage · Heliozoa · Jun 1, 2021 · Jun 1, 2021
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,38 @@
+## Building
+
+Install Rust according to https://www.rust-lang.org/tools/install
+
+Install [zstd](https://github.com/facebook/zstd). For example, on Ubuntu you need the package `libzstd1`. For Windows, download the appropriate archive from the [releases](https://github.com/facebook/zstd/releases), extract it and add the extracted directory to your PATH.
+
+```bash
+git clone git@github.com:rage/tmc-langs-rust.git
+cd tmc-langs-rust
+cargo build
+```
+
+If you have any troubles building the project, please do make an issue!
+
+## Testing
+
+```bash
+cargo test
+```
+
+## Formatting and linting
+
+Use `cargo fmt` and `cargo clippy` for formatting and linting. All crates should have the clippy lints `print_stdout` and `print_stderr` set to deny to allow the CLI to have total control over stdout and stderr. The CLI has one function where writing to stdout is allowed.
+
+## Updating dependencies
+
+For convenience, a tool called [cargo-outdated](https://crates.io/crates/cargo-outdated) can be installed to automatically check all the crates in the workspace for outdated dependencies. You may want to call `cargo update` first to update dependencies to the latest semver-compatible version.
+
+In addition to the dependencies listed in each crate's `Cargo.toml`, the project bundles a few external dependencies such as `tmc-checkstyle-runner`, `tmc-junit-runner` and so on. When updating dependencies, you may want to check whether these projects have been updated.
+
+## Versioning
+
+tmc-langs-rust follows Rust-style semantic versioning, but only for the `tmc-langs-cli` and `tmc-langs` crates. Other crates are considered internal and may go through breaking changes in any release as long as the public API is unaffected.
+
+## Licensing
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
diff --git a/README.md b/README.md
@@ -1,70 +1,12 @@
 Framework for supporting different programming languages in TMC.
 
-TMC-langs provides an interface that encapsulates everything needed to support a new language in TMC. The framework provides CLI wrappers so that it's fairly convenient to call from other languages like Ruby.
+TMC-langs provides an interface that encapsulates everything needed to support a new language in TMC by providing functionality such as downloading exercises, running tests and submitting them. A CLI wrapper is provided so that it's fairly convenient to call from other languages like Ruby.
 
 ## Documentation
 
 Documentation for the latest release is available at https://rage.github.io/tmc-langs-rust
 
-The specifications for various configuration files are included in the spec directory.
-
-The student file policy of each plugin is explained in a `README.md` file in the plugin's subdirectory.
-
-## Building
-
-Install Rust according to https://www.rust-lang.org/tools/install
-
-Install [zstd](https://github.com/facebook/zstd). For example, on Ubuntu you need the package `libzstd1`. For Windows, download the appropriate archive from the [releases](https://github.com/facebook/zstd/releases), extract it and add the extracted directory to your PATH.
-
-```bash
-git clone git@github.com:rage/tmc-langs-rust.git
-cd tmc-langs-rust
-cargo build
-```
-
-If you have any troubles building the project, please do make an issue!
-
-## Testing
-
-```bash
-cargo test
-```
-
-## Running the CLI
-
-```bash
-cargo run -p tmc-langs-cli help
-```
-
-## Development
-
-Format using `cargo fmt`, use `cargo clippy` for linting. All crates should have the clippy lints `print_stdout` and `print_stderr` set to deny. The CLI has one function where writing to stdout is allowed.
-
-If using vscode and rust-analyzer, be sure to turn on the setting `loadOutDirsFromCheck` to avoid a spurious unresolved import error from `isolang`.
-
-## Updating dependencies
-
-In addition to the dependencies listed in each crate's `Cargo.toml`, the project bundles a few external dependencies such as `tmc-checkstyle-runner`, `tmc-junit-runner` and so on. When updating dependencies, you may want to check whether these projects have been updated.
-
-For convenience, a tool called [cargo-outdated](https://crates.io/crates/cargo-outdated) can be installed to automatically check all the crates in the workspace for outdated dependencies. You may want to call `cargo update` first to update dependencies to the latest semver-compatible version.
-
-## Versioning
-
-tmc-langs-rust follows Rust-style semantic versioning, but only for the `tmc-langs-cli` and `tmc-langs` crates. Other crates may go through breaking changes in any release as long as the CLI and langs are unaffected.
-
-## CLI binary deployment and downloads
-
-Documentation and binaries for the supported targets are built and the binaries deployed to Google Cloud when creating a GitHub release. The binaries are available at https://download.mooc.fi/tmc-langs-rust/, with each binary following the file name format `tmc-langs-cli-{target}-{version}(.exe)`, with the `.exe` suffix added for the Windows binaries. For a list of targets see below. For example, The 64-bit Linux binary for version 0.5.0 is available at https://download.mooc.fi/tmc-langs-rust/tmc-langs-cli-x86_64-unknown-linux-gnu-0.5.0.
-
-### Supported targets
-
-- Linux 64-bit (x86_64-unknown-linux-gnu)
-- Linux 32-bit (i686-unknown-linux-gnu)
-- Windows MSVC 64-bit (x86_64-pc-windows-msvc)
-- Windows MSVC 32-bit (i686-pc-windows-msvc)
-- MacOS 64-bit (x86_64-apple-darwin)
-- ARM64 (aarch64-unknown-linux-gnu)
-- Armv7 (armv7-unknown-linux-gnueabihf)
+Additional documentation for other aspects of TMC such as configuration file formats is included in the [docs](./docs) directory.
 
 ## Included projects
 
@@ -74,7 +16,7 @@ A "frontend" for tmc-langs. A binary CLI client for TMC-langs for IDEs. Intended
 
 ### tmc-langs
 
-The "backend". A library that provides a convenient API for implementing different frontends. A frontend (such as a CLI) should only depend on this.
+The "backend". A library that provides a convenient API for implementing different frontends. A frontend (such as a CLI) should only depend on this library. The other libraries are considered internal.
 
 ### tmc-client
 
@@ -86,7 +28,7 @@ A library for creating language plugins.
 
 ### tmc-langs-plugins
 
-A library that provides a convenient API for using all the different plugins.
+A library that provides a convenient API abstracting over all the different language plugins.
 
 ### tmc-langs-util
 
@@ -116,6 +58,19 @@ A TMC plugin for Python 3.
 
 A TMC plugin for R.
 
+### Supported targets
+
+- Linux 64-bit (x86_64-unknown-linux-gnu)
+- Linux 32-bit (i686-unknown-linux-gnu)
+- Windows MSVC 64-bit (x86_64-pc-windows-msvc)
+- Windows MSVC 32-bit (i686-pc-windows-msvc)
+- MacOS 64-bit (x86_64-apple-darwin)
+- ARM64 (aarch64-unknown-linux-gnu)
+- Armv7 (armv7-unknown-linux-gnueabihf)
+
+## Contributing
+See [CONTRIBUTING](CONTRIBUTING.md).
+
 ## License
 
 Licensed under either of
@@ -126,9 +81,3 @@ Licensed under either of
   ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.
-
-## Contribution
-
-Unless you explicitly state otherwise, any contribution intentionally submitted
-for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
-dual licensed as above, without any additional terms or conditions.
diff --git a/tmc-langs-cli/README.md b/tmc-langs-cli/README.md
@@ -1,10 +1,22 @@
 CLI interface for tmc-langs. The documentation for the various commands and parameters are best seen from the CLI itself. For example, running `tmc-langs-cli help clean` will print out the information for the `clean` sub-command. Alternatively, `src/app.rs` contains the CLI definition.
 
+## Running the CLI
+
+Running the project with Cargo from the repository root:
+```bash
+cargo run -p tmc-langs-cli help
+```
+
 ## API format
+
 See the `Output` struct in `src/output.rs` for the type definition that is converted to JSON and printed for every command. See the `api` directory for some examples of what the result looks as JSON. The example files are used in unit tests so they should always be up to date and correct.
 
 In general, the API is structured as follows: there is an `output-kind` field which can have one of several values. Each value corresponds to a kind of message that has some fields associated with it. For example, if the `output-kind` is `output-data`, the message will have the fields `status`, `message`, `result`, and `data`. The `data` field, the value of which is an object, will then contain the field `output-data-kind` which specifies the rest of the fields of the `data` object, and so on.
 
+## Binary deployment and downloads
+
+Documentation and binaries for the supported targets are built and the binaries deployed to Google Cloud when creating a GitHub release. The binaries are available at https://download.mooc.fi/tmc-langs-rust/, with each binary following the file name format `tmc-langs-cli-{target}-{version}(.exe)`, with the `.exe` suffix added for the Windows binaries. For a list of targets see the README at the repository root. For example, The 64-bit Linux binary for version 0.5.0 is available at https://download.mooc.fi/tmc-langs-rust/tmc-langs-cli-x86_64-unknown-linux-gnu-0.5.0.
+
 ## Environment variables
 
 | var name               | usage                                                          |