docs: 🎨 document markdown formatted to standard md format

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 We're excited to have you interested in contributing to MayaStor!
 
-> *Disclaimer:* MayaStor is a **beta** project, and contributors at this stage of the project
+> _Disclaimer:_ MayaStor is a **beta** project, and contributors at this stage of the project
 > lifecycle may experience minor hurdles to contribution.
 >
 > **We want to overcome these. Please report them.**
@@ -29,7 +29,7 @@ need from you.
 
 ### Requesting new features
 
-You are invited to open *complete, well described* issues proposing new features. While MayaStor
+You are invited to open _complete, well described_ issues proposing new features. While MayaStor
 has no formal RFC process at this time, the [Rust RFC template][rust-rfc-template] is an
 excellent place to derive your issue description from.
 
@@ -39,7 +39,7 @@ excellent place to derive your issue description from.
 
 Start work off the `develop` branch. **Not `master`.**
 
-[bors][bors] will merge your commits. We do not do [*squash merges*][squash-merges].
+[bors][bors] will merge your commits. We do not do [_squash merges_][squash-merges].
 
 Each commit message must adhere to [Conventional Commits][conventional-commits]. You can use
 [`convco`][tools-convco] if you would prefer a tool to help.
@@ -63,52 +63,52 @@ Once review is given, Maintainers and SIG members may indicate merge readiness w
 
 Our maintainers are:
 
-* [@gila][members-gila] - [@mayadata-io][maya-data]
-* [@jkryl][members-jkryl] - [@mayadata-io][maya-data]
-* [@GlennBullingham][members-GlennBullingham] - [@mayadata-io][maya-data]
+- [@gila][members-gila] - [@mayadata-io][maya-data]
+- [@jkryl][members-jkryl] - [@mayadata-io][maya-data]
+- [@GlennBullingham][members-glennbullingham] - [@mayadata-io][maya-data]
 
 Our Special Interest Groups (SIGs) are:
 
-* Dataplane
-  + [@hoverbear][members-hoverbear] - [@mayadata-io][maya-data] &
+- Dataplane
+  - [@hoverbear][members-hoverbear] - [@mayadata-io][maya-data] &
     [@Hoverbear-Consulting](https://github.com/Hoverbear-Consulting)
-  + [@mtzaurus][members-mtzaurus] - [@mayadata-io][maya-data]
-  + [@jonathan-teh][members-jonathan-teh] - [@mayadata-io][maya-data]
-* e2e-testing
-  + [@chriswldenyer][members-chriswldenyer] - [@mayadata-io][maya-data]
-  + [@blaisedias][members-blaisedias] - [@mayadata-io][maya-data]
-* Control Plane
-  + [@tiagolobocastro][members-tiagolobocastro] - [@mayadata-io][maya-data]
-  + [@paulyoong][members-paulyoong] - [@mayadata-io][maya-data]
+  - [@mtzaurus][members-mtzaurus] - [@mayadata-io][maya-data]
+  - [@jonathan-teh][members-jonathan-teh] - [@mayadata-io][maya-data]
+- e2e-testing
+  - [@chriswldenyer][members-chriswldenyer] - [@mayadata-io][maya-data]
+  - [@blaisedias][members-blaisedias] - [@mayadata-io][maya-data]
+- Control Plane
+  - [@tiagolobocastro][members-tiagolobocastro] - [@mayadata-io][maya-data]
+  - [@paulyoong][members-paulyoong] - [@mayadata-io][maya-data]
 
 Former SIGs (and their members) are:
 
-* None, yet!
+- None, yet!
 
 ### Organization FAQs
 
-* **What is a *Maintainer*?**
+- **What is a _Maintainer_?**
 
   Maintainers are the project architects. They have the final say on what features get accepted,
   what code gets merged, when releases are cut, and how the project evolves.
 
   Maintainers **must** make decisions unanimously, no majorities, no votes.
 
-* **What is a *Special Interest Group (SIG)*?**
+- **What is a _Special Interest Group (SIG)_?**
 
   SIGs are small ephemeral teams (max 7) working on a general topic.
 
   They may change at any time, and have no strict definition.
 
   SIGs may be created, empowered, and destroyed by the maintainers at any time.
 
-* **Are there other levels/roles/organization structure?**
+- **Are there other levels/roles/organization structure?**
 
   No. We want to focus on building MayaStor.
 
   It's preferable that we flow like water as opposed to become a rue goldberg machine of rules.
 
-* **May I join a SIG? Become a maintainer?**
+- **May I join a SIG? Become a maintainer?**
 
   Of course, we'd love that!
 
@@ -124,7 +124,7 @@ Former SIGs (and their members) are:
 [mayastor-slack-inviter]: https://slack.k8s.io/
 [members-gila]: https://github.com/gila
 [members-jkryl]: https://github.com/jkryl
-[members-GlennBullingham]: https://github.com/GlennBullingham
+[members-glennbullingham]: https://github.com/GlennBullingham
 [members-hoverbear]: https://github.com/hoverbear
 [members-tiagolobocastro]: https://github.com/tiagolobocastro
 [members-mtzaurus]: https://github.com/mtzaurus
@@ -137,4 +137,4 @@ Former SIGs (and their members) are:
 [bors]: https://bors.tech/
 [squash-merges]: https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits
 [conventional-commits]: https://www.conventionalcommits.org/en/v1.0.0/
-[tools-convco]: https://convco.github.io/
+[tools-convco]: https://convco.github.io/

doc/FAQ.md

@@ -1,3 +1,5 @@
+# FQA
+
 ## Why user space?
 
 As we target cloud native workloads, depending on kernel features is not possible. For example, the Ubuntu image
@@ -14,7 +16,7 @@ NVMe is a protocol that specifies how data is moved between the CPU and a PCIe d
 because CPUs in terms of speed is relatively stable, but the number of cores keeps increasing.
 Also with SSD devices, the CPUs are starting to become the bottleneck.
 
-In short, it meant that  a whole new design was needed (which is not completely new as it borrows a lot
+In short, it meant that a whole new design was needed (which is not completely new as it borrows a lot
 from InfiniBand).
 
 ## Can NVMe only be used with NVMe devices?
@@ -53,4 +55,3 @@ GRUB_CMDLINE_LINUX_DEFAULT=isolcpu="1,3"
 The same set of CPU's should be passed on to Mayastor and during startup the it will pin itself to the cores given. Initially
 this might look cumbersome, but in turns out in practice, due to many core systems these days, it actually provides a very
 predictable and scaling model.
-

doc/build.md

@@ -12,9 +12,9 @@ you won't need to worry about cross compiler toolchains, and all builds are repr
 
 ## Table of Contents
 
-* [Prerequisites](#Prerequisites)
-* [Iterative Builds](#Iterative-Builds)
-* [Artifacts](#Artifacts)
+- [Prerequisites](#Prerequisites)
+- [Iterative Builds](#Iterative-Builds)
+- [Artifacts](#Artifacts)
 
 ## Prerequisites
 
@@ -23,14 +23,14 @@ Windows, FreeBSD, OpenWRT, or other server platforms.
 
 If you do not have Linux system:
 
-* **Windows:** We recommend using [WSL2][windows-wsl2] if you only need to
+- **Windows:** We recommend using [WSL2][windows-wsl2] if you only need to
   build Mayastor. You'll need a [Hyper-V VM][windows-hyperv] if you want to use it.
-* **Mac:** We recommend you use [Docker for Mac][docker-install]
+- **Mac:** We recommend you use [Docker for Mac][docker-install]
   and follow the Docker process described. Please let us know if you find a way to
   run it!
-* **FreeBSD:** We *think* this might actually work, SPDK is compatible! But, we haven't
+- **FreeBSD:** We _think_ this might actually work, SPDK is compatible! But, we haven't
   tried it yet.
-* **Others:** This is kind of a "Do-it-yourself" situation. Sorry, we can't be more help!
+- **Others:** This is kind of a "Do-it-yourself" situation. Sorry, we can't be more help!
 
 The only thing your system needs to build Mayastor is [**Nix**][nix-install].
 
@@ -45,6 +45,7 @@ curl -L https://nixos.org/nix/install | sh
 > That's totally fine. You can use [`docker`][docker-install] just fine for one-off or occasional PRs!
 >
 > This flow will get you a pre-fetched `nix` store:
+>
 > ```bash
 > docker run --name mayastor-nix-prefetch -it -v $(pwd):/scratch:rw --privileged --workdir /scratch nixos/nix nix-shell --run "exit 0"
 > docker commit mayastor-nix-prefetch mayastor/dev-env:latest
@@ -54,9 +55,8 @@ curl -L https://nixos.org/nix/install | sh
 >
 > To re-enter, just run the last command again.
 
-
-* Some of our team uses [NixOS][nixos] which has `nix` baked in, but you don't need to.
-* Some of our team uses [`direnv][direnv], but you don't need to.
+- Some of our team uses [NixOS][nixos] which has `nix` baked in, but you don't need to.
+- Some of our team uses [`direnv][direnv], but you don't need to.
 
 For some tasks, we use features from `nixUnstable`. You can use `nixos-unstable`
 **(or `nixpkgs-unstable` for `nix` users)** by [changing your channel][nix-channel].
@@ -83,20 +83,21 @@ $ sudo nixos-rebuild switch --update
 ```
 
 > If you don't want, you can drop into a
-`nixUnstable` supporting shell with:
+> `nixUnstable` supporting shell with:
 >
 > ```bash
 > nix-shell -I nixpkgs=channel:nixpkgs-unstable -p nixUnstable --command "nix --experimental-features 'nix-command flakes' develop -f . mayastor"
 > ```
 >
 > Don't want to use `nixUnstable`? **That's ok!** Use `nix-shell` and `nix-build` as you normally would.
 
-**Want to run or hack on Mayastor?** *You need more configuration!* See
+**Want to run or hack on Mayastor?** _You need more configuration!_ See
 [running][doc-run], then [testing][doc-test].
 
-
 You can use a tool like [`direnv`][direnv] to automate `nix shell` entry.
-If you are unable to use the Nix provided Rust for some reason, there are `norust` and `nospdk` arguments to Nix shell. `nix-shell --arg norust true`
+If you are unable to use the Nix provided Rust for some reason, there are `norust` and
+`nospdk` arguments to Nix shell. `nix-shell --arg norust true`
+
 ## Iterative Builds
 
 Contributors often build Mayastor repeatedly during the development process.
@@ -117,22 +118,24 @@ cargo build
 cargo build --release
 ```
 
-**Want to run or hack on Mayastor?** *You need more configuration!* See
+**Want to run or hack on Mayastor?** _You need more configuration!_ See
 [running][doc-running], then [testing][doc-testing].
 
 To ensure you are aware of this, we greet you with a nice cow.
 
 ## Artifacts
 
 There are a few ways to build Mayastor! If you're hacking on Mayastor, it's best to use
-[`nix develop`][nix-develop] (above) then turn to traditional Rust tools. If you're looking for releases, use [`nix build`][nix-build] or [`nix bundle`][nix-bundle] depending on your needs.
+[`nix develop`][nix-develop] (above) then turn to traditional Rust tools. If you're looking for releases,
+use [`nix build`][nix-build] or [`nix bundle`][nix-bundle] depending on your needs.
 
 > **Why is the build process this way?**
 >
-> Mayastor creates [*reproducable builds*][reproducable-builds], it won't use any of your
+> Mayastor creates [_reproducable builds_][reproducable-builds], it won't use any of your
 > local system dependencies (other than `nix`). This is a component of the best practices of the
 > [Core Infrastructure Initiative][cii-best-practices]. More on how Nix works can be found in the
 > [Nix paper][nix-paper].
+
 ### Building non-portable Nix derivations
 
 You can build release binaries of Mayastor with [`nix build`][nix-build]:

doc/csi.md

@@ -7,10 +7,10 @@ document.
 Basic workflow starting from registration is as follows:
 
 1. csi-node-driver-registrar retrieves information about csi plugin (mayastor) using csi identity service.
-2. csi-node-driver-registrar registers csi plugin with kubelet passing plugin's csi endpoint as parameter.
-3. kubelet uses csi identity and node services to retrieve information about the plugin (including plugin's ID string).
-4. kubelet creates a custom resource (CR) "csi node info" for the CSI plugin.
-5. kubelet issues requests to publish/unpublish and stage/unstage volume to the CSI plugin when mounting the volume.
+1. csi-node-driver-registrar registers csi plugin with kubelet passing plugin's csi endpoint as parameter.
+1. kubelet uses csi identity and node services to retrieve information about the plugin (including plugin's ID string).
+1. kubelet creates a custom resource (CR) "csi node info" for the CSI plugin.
+1. kubelet issues requests to publish/unpublish and stage/unstage volume to the CSI plugin when mounting the volume.
 
 The registration of mayastor storage nodes with control plane (moac) is handled
 by a separate protocol using NATS message bus that is independent on CSI plugin.

doc/errors.md

@@ -24,7 +24,7 @@ Snafu is one of many libraries in rust for representing failures. We picked
 snafu because:
 
 1. It seems relatively popular in rust
-2. It provides an elegant way of chaining errors and the definition of errors and error
+1. It provides an elegant way of chaining errors and the definition of errors and error
    messages makes use of a preprocessor and is easy.
 
 An example of an error definition follows. We introduce a new enum type with three
@@ -61,20 +61,20 @@ results from async callbacks to avoid code duplication.
    potential mayastor errors we want them to be defined where they are used.
    The error definition can be per file or per group of closely related files.
 
-2. Error names should be short, clear and consistent across the whole
+1. Error names should be short, clear and consistent across the whole
    code base. If the error is a high level error specifying context of the
    error, its name should be `Operation` + `Object` (i.e. `CreateReplica`). If
    the error describes the root cause of a problem, then the name should be
    `Object` + `Problem` (i.e. `PoolNotFound`).
 
-3. Take care to assign the right context data to the right layer or errors.
+1. Take care to assign the right context data to the right layer or errors.
    For example if we have a high level `CreateReplica` error, that's where
    `uuid` of the replica should be mentioned. There may be 10 different reasons why
    the create operation failed, and those reasons (errors) may contain more
    detailed information. However, all those 10 errors don't need to contain uuid, because
    that information is already added by the `CreateReplica` context.
 
-4. Errors returned by RPC methods must implement `RpcErrorCode` trait. This
+1. Errors returned by RPC methods must implement `RpcErrorCode` trait. This
    is a specific requirement to mayastor because the RPC handler must know
    which RPC error code to associate with the error. Low level errors which
    aren't directly passed to RPC handlers don't need to implement the trait.
@@ -110,6 +110,7 @@ pub enum Error {
     // ...
 }
 ```
+
 ```rust
 create_target(addr).context(CreateTarget { nqn })?;
 ```
@@ -244,10 +245,11 @@ We have seen how the tree of errors from the least specific context errors to
 most specific root cause errors implemented. Now let's see it in action.
 What is behind the following log file:
 
-```
+```bash
 jsonrpc.rs: 218:: *ERROR*: Failed to create replica dbe4d7eb-118a-4d15-b789-a18d9af6ff21: Replica already exists
 ```
 
 A stack of composable errors:
+
 1. `Failed to create replica dbe4d7eb-118a-4d15-b789-a18d9af6ff21`
-2. `Replica already exists`
+1. `Replica already exists`