doc: port existing content

Signed-off-by: Brian McGee <[email protected]>

docs/.vitepress/config.mts

@@ -11,17 +11,16 @@ export default defineConfig({
     // https://vitepress.dev/reference/default-theme-config
     nav: [
       { text: 'Home', link: '/' },
-      { text: 'Examples', link: '/markdown-examples' }
+      { text: 'Quick Start', link: '/quick-start' }
     ],
 
     sidebar: [
-      {
-        text: 'Examples',
-        items: [
-          { text: 'Markdown Examples', link: '/markdown-examples' },
-          { text: 'Runtime API Examples', link: '/api-examples' }
-        ]
-      }
+      { text: 'Quick Start', link: '/quick-start' },
+      { text: 'Overview', link: '/overview' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Formatter Spec', link: '/formatter-spec' },
+      { text: 'Contributing', link: '/contributing' },
+      { text: 'FAQ', link: '/faq' },
     ],
 
     socialLinks: [

docs/contributing.md

@@ -0,0 +1,145 @@
+---
+outline: deep
+---
+
+# Contribution guidelines
+
+This file contains instructions that will help you make a contribution.
+
+## Licensing
+
+The treefmt binaries and this user guide are licensed under the [MIT license](https://numtide.github.io/treefmt/LICENSE.html).
+
+## Before you contribute
+
+Here you can take a look at the [existing issues](https://github.com/numtide/treefmt/issues). Feel free to contribute, but make sure you have a [GitHub account](https://github.com/join) first :) .
+
+If you're new to open source, please read GitHub's guide on [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/). It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects.
+
+Before sending a pull request, make sure that you've read all the guidelines. If you don't understand something, please [state your question clearly in an issue](https://github.com/numtide/treefmt/issues/new) or ask the community on the [treefmt matrix server](https://matrix.to/#/#treefmt:numtide.com).
+
+## Creating an issue
+
+If you need to create an issue, make sure to clearly describe it, including:
+
+-   The steps to reproduce it if it's a bug
+-   The version of treefmt used
+-   The database driver and version
+-   The database version
+
+The cache database is stored in a toml file the ~/.cache/treefmt directory.
+
+## Making changes
+
+If you want to introduce changes to the project, please follow these steps:
+
+-   Fork the repository on GitHub
+-   Create a branch on your fork. Don't commit directly to main
+-   Add the necessary tests for your changes
+-   Run treefmt in the source directory before you commit your changes
+-   Push your changes to the branch in your repository fork
+-   Submit a pull request to the original repository
+
+Make sure you based your commits on logical and atomic units!
+
+## Examples of git history
+
+Git history that we want to have:
+
+Git history that we are trying to avoid:
+
+<details>
+
+<summary>Git history that we want to have</summary>
+
+```
+
+*   e3ed88b (HEAD -> contribution-guide, upstream/main, origin/main, origin/HEAD, main) Merge pull request #470 from zimbatm/fix_lru_cache
+
+|\
+
+| * 1ab7d9f Use rayon for multithreading command
+
+|/
+
+*   e9c5bb4 Merge pull request #468 from zimbatm/multithread
+
+|\
+
+| * de2d6cf Add lint property for Formatter struct
+
+| * cd2ed17 Fix impl on Formatter get_command() function
+
+|/
+
+*   028c344 Merge pull request #465 from rayon/0.15.0-release
+
+|\
+
+| * 7b619d6 0.15.0 release
+
+|/
+
+*   acdf7df Merge pull request #463 from zimbatm/support-multi-part-namespaces
+
+```
+
+</details>
+
+<details>
+
+<summary>Git history that we are <b>trying</b> to avoid:</summary>
+
+```
+
+*   4c8aca8 Merge pull request #120 from zimbatm/add-rayon
+
+|\
+
+| * fc2b449 use rayon for engine now
+
+| * 2304683 add rayon config
+
+| * 5285bd3 bump base image to F30
+
+* |   4d0fbe2 Merge pull request #114 from rizary/create_method_create_release
+
+|\ \
+
+| * | 36a9396 test changed
+
+| * | 22f681d method create release for github created
+
+* | |   2ef4ea1 Merge pull request #119 from rizary/config.rs
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 5f1b8f0 unused functions removed
+
+* | |   a93c361 Merge pull request #117 from zimbatm/add-getreleases-to-abstract
+
+|\ \ \
+
+| |/ /
+
+|/| |
+
+| * | 0a97236 add get_releses for Cargo
+
+| * | 55e4c57 add get_releases/get_release into engine.rs
+
+|/ /
+
+* |   badeddd Merge pull request #101 from zimbatm/extreme-cachin
+
+```
+
+</details>
+
+Additionally, it's always good to work on improving documentation and adding examples.
+
+Thank you for considering contributing to `treefmt`.

docs/faq.md

@@ -0,0 +1,19 @@
+# FAQ
+
+## How does treefmt function?
+
+`Treefmt` traverses all your project's folders, maps files to specific code formatters, and formats the code accordingly. Other tools also traverse the filesystem, but not necessarily starting from the root of the project.
+
+Contrary to other formatters, `treefmt` doesn't preview the changes before writing them to a file. If you want to view the changes, you can always check the diff in your version control (we assume that your project is checked into a version control system). You can also rely on version control if errors were introduced into your code as a result of disruptions in the formatter's work.
+
+## How is the cache organized?
+
+At this moment, the cache is represented by a flat TOML file where file paths are mapped to `mtimes`. The file is located in:
+
+```
+~/.cache/treefmt/<hash-of-the-treefmt.toml-path>.toml
+```
+
+However, we are planning to move the hash file to the destination project's root directory.
+
+At the end of each tool run, the cache file gets overwritten with the last formatting time entries. In this way, we can can compare the last change time of the file to the last formatting time, and figure out which files need re-formatting.

docs/formatter-spec.md

@@ -0,0 +1,55 @@
+---
+outline: deep
+---
+
+# Formatter Specification
+
+In order to keep the design of `treefmt` simple, we support only formatters which adhere to a certain standard. This document outlines this standard. If the formatter you would like to use doesn't comply with the rules, it's often possible to create a wrapper script that transforms the usage to match the specification.
+
+In this design, we rely on `treefmt` to do the tree traversal, and only invoke
+the code formatter on the selected files.
+
+## Rules
+
+In order for the formatter to comply to this spec, it MUST follow the
+following rules:
+
+### 1. Files passed as arguments
+
+In order to be integrated to `treefmt`'s workflow, the formatter's CLI must adhere to the following specification:
+
+```
+<command> [options] [...<files>]
+```
+
+Where:
+
+-   `<command>` is the name of the formatting tool.
+-   `[options]` is any number of flags and options that the formatter accepts.
+-   `[...<files>]` is one or more files given to the formatter for processing.
+
+Example:
+
+```
+$ rustfmt --edition 2018 src/main.rs src/lib.rs
+```
+
+It SHOULD processes only the specified files. Files that are not passed SHOULD never be formatted.
+
+### 2. Write to changed files
+
+Whenever there is a change to the code formatting, the code formatter MUST
+write to the changes back to the original location.
+
+If there is no changes to the original file, the formatter MUST NOT write to
+the original location.
+
+### 3. Idempotent
+
+The code formatter SHOULD be indempotent. Meaning that it produces stable
+outputs.
+
+### 4. Reliable
+
+We expect the formatter to be reliable and not break the semantic of the
+formatted files.