Skip to content

Commit

Permalink
Swapped section order
Browse files Browse the repository at this point in the history
Swapped the "Usage" and "Setup" sections in README.md, to aid reading
order.
  • Loading branch information
danwilliams committed Jun 15, 2023
1 parent 39ca65f commit cc21aa8
Showing 1 changed file with 77 additions and 77 deletions.
154 changes: 77 additions & 77 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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`.
Expand Down

0 comments on commit cc21aa8

Please sign in to comment.