diff --git a/README.md b/README.md index 156a331..5847ebf 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ The main sections in this README are: - [Content](#content) - [Features](#features) - [Why Rustmark?](#why-rustmark) - - [Setup](#setup) - [Usage](#usage) + - [Setup](#setup) - [Deployment](#deployment) - [Legal](#legal) @@ -222,82 +222,6 @@ future, probably with a configuration setting to control whether everything is built into the binary or left externally to be deployed alongside it. -## Setup - -The steps to set up this project are simple and standard. You need a -reasonably-recent Rust environment, on a Linux machine. There are currently no -special requirements beyond what is needed to build a standard Rust project. - -Note that these instructions are for building the application yourself, which -will usually be in context of having created a [new Rustmark project](#getting-started) -by cloning, forking, or possibly using the Rustmark repository as a template. In -this case these steps will apply for your new project. You can also download the -crate using `cargo install rustmark`, which will install the latest version of -Rustmark from crates.io, but this currently is not particularly useful beyond -letting you poke at the default, running application without having to clone the -repository and build it yourself, to see if you like it. See the [Getting -started](#getting-started) section for more information on creating a project -using based on Rustmark. - -### Environment - -There are some key points to note about the environment you choose: - - - Debian and Ubuntu are the Linux distros of choice, although other distros - should also work just fine, as there are no special requirements. - - Running natively on Windows is not targeted or tested, and there are no - plans to support it, so although it may work, it also may not. Running on - WSL does work fine, and is the recommended way to run on Windows. - - Running natively on MacOS is untested, although there is no known technical - reason why it would not work. - -Typically, you will set up Rust using [`rustup`](https://rustup.rs/), which is -the recommended way to install Rust. The `stable` toolchain is targeted, as the -focus is on stability and correctness, rather than bleeding-edge features. - -Once you have Rust installed, you can build the project using `cargo build`. -This will download and compile all dependencies, and build the project. You can -then run the project using `cargo run`. - -### Configuration - -Rustmark is configured using a TOML file. The default configuration file is -`Config.toml`, which should be placed in the same directory as the binary. The -configuration settings (and file) are optional, and if not provided, Rustmark -will use default values for all configuration options. - -It is also possible to pass configuration parameters from the command line, as -environment variables. The environment variables take precedence over the -configuration file options. - -### Running - -Rustmark can be run using the `cargo run` command, or by running the compiled -binary directly. The server will listen on port 8000 by default, and will serve -content from the `markdown` and `static` directories. The `markdown` directory -contains the Markdown files to be rendered, and the `static` directory contains -the static files to be served. - -### Testing - -You can run the test suite using `cargo test`. This will run all unit and -integration tests. - -**Note that, at present, there are no tests written specifically for this -project, as it is mostly a combination of other crates from the Rust ecosystem. -Tests might be added when the project is more mature and sensible things to test -have been clearly identified.** - -### Documentation - -You can build the developer documentation using `cargo doc`. This will generate -HTML files and place them into `target/doc`. You can then open the documentation -in your browser by opening `target/doc/rustmark/index.html`. - -Building the documentation for local development use will also provide you with -links to the source code. - - ## Usage The Rustmark repository is designed so that it can be forked, and content added. @@ -392,6 +316,82 @@ also find information there about the [coding standards](https://github.com/danw used. +## Setup + +The steps to set up this project are simple and standard. You need a +reasonably-recent Rust environment, on a Linux machine. There are currently no +special requirements beyond what is needed to build a standard Rust project. + +Note that these instructions are for building the application yourself, which +will usually be in context of having created a [new Rustmark project](#getting-started) +by cloning, forking, or possibly using the Rustmark repository as a template. In +this case these steps will apply for your new project. You can also download the +crate using `cargo install rustmark`, which will install the latest version of +Rustmark from crates.io, but this currently is not particularly useful beyond +letting you poke at the default, running application without having to clone the +repository and build it yourself, to see if you like it. See the [Getting +started](#getting-started) section for more information on creating a project +using based on Rustmark. + +### Environment + +There are some key points to note about the environment you choose: + + - Debian and Ubuntu are the Linux distros of choice, although other distros + should also work just fine, as there are no special requirements. + - Running natively on Windows is not targeted or tested, and there are no + plans to support it, so although it may work, it also may not. Running on + WSL does work fine, and is the recommended way to run on Windows. + - Running natively on MacOS is untested, although there is no known technical + reason why it would not work. + +Typically, you will set up Rust using [`rustup`](https://rustup.rs/), which is +the recommended way to install Rust. The `stable` toolchain is targeted, as the +focus is on stability and correctness, rather than bleeding-edge features. + +Once you have Rust installed, you can build the project using `cargo build`. +This will download and compile all dependencies, and build the project. You can +then run the project using `cargo run`. + +### Configuration + +Rustmark is configured using a TOML file. The default configuration file is +`Config.toml`, which should be placed in the same directory as the binary. The +configuration settings (and file) are optional, and if not provided, Rustmark +will use default values for all configuration options. + +It is also possible to pass configuration parameters from the command line, as +environment variables. The environment variables take precedence over the +configuration file options. + +### Running + +Rustmark can be run using the `cargo run` command, or by running the compiled +binary directly. The server will listen on port 8000 by default, and will serve +content from the `markdown` and `static` directories. The `markdown` directory +contains the Markdown files to be rendered, and the `static` directory contains +the static files to be served. + +### Testing + +You can run the test suite using `cargo test`. This will run all unit and +integration tests. + +**Note that, at present, there are no tests written specifically for this +project, as it is mostly a combination of other crates from the Rust ecosystem. +Tests might be added when the project is more mature and sensible things to test +have been clearly identified.** + +### Documentation + +You can build the developer documentation using `cargo doc`. This will generate +HTML files and place them into `target/doc`. You can then open the documentation +in your browser by opening `target/doc/rustmark/index.html`. + +Building the documentation for local development use will also provide you with +links to the source code. + + ## Deployment You can build the project in release mode by using `cargo build --release`.