Merge pull request #55 from thedataquarry/docs-update

Docs update

CONTRIBUTING.md

@@ -1,7 +1,15 @@
+# Contributing guide
+
 Thank you for your interest in contributing to the _Rust In Pieces_ project!
 
 There are a few ways of helping: critiquing the documentation and/or code examples, fixing
-incorrect information, and fixing bugs.
+incorrect information, fixing bugs, and fixing errors in the book.
+
+Contributions can be made in two places: the _code_ and the _book_.
+
+## Code
+
+The code is in the [pieces](./pieces) directory.
 
 It is encouraged for you to run the tests, formatters, and linters before submitting PRs. They will
 all need to pass before the PR can be merged so you can save youself some time by running them
@@ -49,22 +57,44 @@ cargo test --quiet
 cargo run --quiet
 ```
 
-## Critiquing the documentation and/or code
+### Critiquing the documentation and/or code
 
 This is the easiest way to contribute. Basically, as you read the documentation or experiment with
 the code samples, if you find something confusing, incorrect, or missing, then you can file an
 [issue](https://github.com/thedataquarry/rustinpieces/issues) explaining your concerns.
 
-## Fixing incorrect information
+### Fixing incorrect information
 
 If you find typos or incorrect links we welcome PRs to fix them. For these types of fixes there is
 no need to open an issue first. For larger changes (or potentially adding a new piece), you are
 encouraged to first open an issue to discuss the change before taking the time to make changes.
 
-## Fixing bugs
+### Fixing bugs
 
 If you find a bug in the code examples as you work through them, PRs for fixes are welcome. When
 fixing a bug in either a Python or Rust file please check the other language's corresponding file
 to see if the same bug exists there. If you know how to fix both then you can do both in one PR. If
 you are unsure how to make the fix in one language let us know in your PR description so we can make
 the additional fix.
+
+### Adding a new piece (maybe)
+
+It's recommended to start a
+[discussion](https://github.com/thedataquarry/rustinpieces/discussions/categories/ideas)
+prior to putting in the work to add a new piece. This will help ensure that the piece is a good fit
+for the project and that there is interest in it.
+
+## Book
+
+The [book](./book) is written using [mdbook](https://github.com/rust-lang/mdBook), a minimalist
+Rust-based framework to write books in Markdown. It's hosted on GitHub Pages and is available at
+[rustinpieces.dev](https://rustinpieces.dev).
+
+### Fixing errors in the book
+
+If you find an error in the book's text or code blocks, please open a PR with the fix.
+If you are unsure how to fix the error, please open an
+[issue](https://github.com/thedataquarry/rustinpieces/issues) instead.
+
+It's strongly recommended to build and test locally prior to pushing any fixes.
+See the book's [README.md](./book/README.md) for instructions on how to build and run the book locally.

README.md

@@ -43,3 +43,7 @@ A roadmap for upcoming pieces is shown below. Stay tuned!
 | REST API to local LLM        | APIs          | axum, LLMs                               |
 | PyO3 mock data generation    | Unification   | TBD                                      |
 | PyO3 query local LLM         | Unification   | TBD                                      |
+
+## Contributing
+
+Contributions and improvements from the community are welcome! Please see the [contributing guidelines](./CONTRIBUTING.md).

book/README.md

@@ -0,0 +1,51 @@
+# Building the Book
+
+This page contains the source code for the book _Rust in Pieces_, written in
+Markdown.
+
+## Setup
+
+To build and run the book locally, you'll need to install
+[mdBook](https://github.com/rust-lang/mdBook).
+
+Assuming you have Rust installed, you can install `mdbook` with Cargo:
+
+```bash
+cargo install mdbook
+```
+
+This builds mdBook from source on your machine. Alternatively, if you're
+using macOS, you can install it with Homebrew:
+
+```bash
+brew install mdbook
+```
+
+## Build and serve
+
+To run the book locally, run the following command from this level of the
+repository (after running `cd book`):
+
+```bash
+mdbook serve --open
+```
+
+This builds and serves the book on localhost. The `--open` flag will open the
+book in your default browser.
+
+## Run tests
+
+It's strongly recommended to run tests prior to pushing any updates.
+
+```bash
+mdbook test
+```
+
+This runs mdBook's test suite, which checks for broken links and incorrectly
+formatted Rust code blocks.
+
+> [!NOTE]
+> mdBook will test all code blocks in the book that are marked as
+> `rust` or `rs`. If you leave a code block unmarked (i.e., just enclose
+> code in triple backticks), **the test suite will fail**, so make sure to
+> mark all code blocks, including bash/console with the appropriate language.