Docs (#34)

* First pass at having a README

* Add more explainers to the README

* Starting writing about how to write new bindings

* More documentation

* Finish up the writing_bindings.md document

* Add more documentation on linking to libraries and including header files

* Spelling fixes and doc tweaks

README.md

@@ -2,8 +2,121 @@
 
 Rust bindings to OpenCascade. The code is currently a major work in progress.
 
+## Major Goals
+* Define 3D CAD models suitable for 3D printing or machining, in ergonomic Rust code
+* Code-first approach, but allow use of a GUI where it makes sense (2D sketches)
+* Support fillets, chamfers, lofts, surface filling, pipes, extrusions, revolutions, etc.
+* Support quick compile times for faster iterations
+* Ability to import/export STEP files, STL files, SVG, DXF, KiCAD files, and hopefully more!
+* Easy to install the viewer app (provide pre-built binaries for major platforms)
+* Easy to create and use user-authored libraries (via crates.io) for quick and easy code-sharing
+* Pretty visualizations of created parts
+* Ability to specify assemblies of parts, and constraints between assembled parts
+
+## Rationale
+
+This project was born out of me designing [my own keyboard](https://github.com/bschwind/key-ripper) and wanting to make a 3D-printed or CNCed aluminum case for it. In typical over-engineering fashion, I didn't want to just use Fusion360 and call it a day. I wanted a fully parameterized, fully open-source, code-based approach so I can easily make changes, and store the model code in version control. I also want to be fairly confident I can build these models any time in the future given I have a C++/Rust toolchain available.
+
+So I researched what kernels are out there, learned that OpenCascade is one of the few open-source B-Rep (boundary representation) kernels available, and started writing bindings to it with cxx.rs to see if usage of the kernel is feasible. Turns out it is!
+
+### Why Rust?
+
+At this point I'm most comfortable with Rust, so most tools I build will be with Rust. I also don't find any joy in creating my own language or forcing people to learn one I created. Rust is a far better language than I could ever make myself, and contains pretty much every facility I would want for defining 3D models in code. Ultimately it's a hobby project and when you run a hobby project, you get to pick whatever you want :)
+
+There are other benefits:
+
+* Easy to install the Rust toolchain
+* Strong type system can inform you what you can do with say, a `Wire` or a `Shape`
+* Great generated documentation
+* Good cross-platform support
+* Excellent library ecosystem on crates.io, making parts sharing a breeze
+* High level Rust can be ergonomic, with iterators, closures, operator overloading, and enums
+* Rust's unique (`&mut T`) and shared (`&T`) references and function type signatures inform you when an operation modifies a shape vs. creating a new one
+
+## Dependencies
+
+* Rust Toolchain (https://rustup.rs/)
+* CMake (https://cmake.org/)
+* A C++ compiler with C++11 support
+
+## Building
+
+* The `OCCT` codebase is included as a git submodule. Clone the repo with the `--recursive` flag, or use `git submodule update --init` to fetch the submodule.
+* `cargo build --release`
+
+## Run Examples
+
+* `cargo run --release --example bottle`
+
+### Lower Level
+
+There are low level examples which are more or less directly calling OpenCascade functions, such as the classic OpenCascade [bottle](./crates/opencascade-sys/examples/bottle.rs) example, or a [simpler](./crates/opencascade-sys/examples/simple.rs) one.
+
+### Higher Level
+
+The [higher level examples](./crates/opencascade/examples) use more ergonomic Rust APIs, though the exact API is still in flux and subject to change.
+
+## Viewer Application
+
+There is currently an experimental viewer application based on WGPU, which will probably become the "main" way people use this crate. It currently visualizes a hardcoded model produced in Rust code, but will expand to be capable of loading Rust model code compiled to WASM, allowing faster compile times and more interactive inspection of the sketches and models.
+
+You can run the current viewer app with
+
+```
+$ cargo run --release --bin viewer
+```
+
 ## Code Formatting
 
+### Rust Code
 ```
 $ cargo +nightly fmt
 ```
+
+### C++ Code
+```
+$ clang-format -i crates/opencascade-sys/include/wrapper.hxx
+```
+
+## Comparison to other tools
+
+### OpenCascade C++ API
+
+This is probably an obvious one, but I use Rust in order to avoid using C++ when possible. You can use OpenCascade directly in its native language, C++, and some people do! I don't have the patience or mental fortitude for it, though. This method of course gives you the full power of OpenCascade without having to write bindings or higher-level wrappers for it.
+
+### [OpenSCAD](https://openscad.org/)
+
+OpenSCAD is how I started with code-based CAD, and it's still a nice tool with lots of community projects and libraries invested into it. To me though, there are several downsides:
+
+* The language is clumsy and limited compared to modern programming languages
+* The CAD kernel is CGAL, which is mesh-based. There is less semantic information about geometry, and parts end up just being a soup of triangles.
+* Fillets, chamfers, and curves in general end up being more of a pain compared to a B-Rep (Boundary Representation) CAD kernel
+* No ability to export STEP files
+
+
+### [CadQuery](https://cadquery.readthedocs.io/en/latest/)
+
+This project is extremely similar to CadQuery, and owes a lot of its inspiration to it. I mostly like CadQuery, except:
+
+* It's a Python tool, and managing Python dependencies and installations just isn't fun
+* The usage of the "fluent" API produces code that is hard to visualize, you have to keep a lot on your mental stack to understand what a given snippet is doing.
+
+These are small complaints, and to the second point, I'm pretty sure you can write more imperative CadQuery code which spells out more obviously what is going on.
+
+I'd say CadQuery is an _excellent_ tool, and likely the most fully-featured code-based CAD tool out there that I'm aware of.
+
+So if you like Python and have patience to deal with Python installations and such, absolutely go with CadQuery. It'll take this project quite awhile to reach feature parity with it.
+
+### [Cascade Studio](https://github.com/zalo/CascadeStudio)
+
+Like CadQuery, Cascade Studio is also based on the OpenCascade kernel. It's quite nice as well, and has an [incredible manual](https://github.com/raydeleu/CascadeStudioManual) with tons of detail. I was mainly turned off by the fact that you have to use the GUI to discover edge indices, which you then pass to the `FilletEdges()` function as a list of numbers. These indices can change as you modify the shape, and it all feels a bit unstable and relies too much on mouse picking from the GUI.
+
+But its web browser support and relatively simple JavaScript API make it a nice, approachable tool if you want to create models quickly.
+
+### [Fornjot](https://github.com/hannobraun/fornjot)
+
+Fornjot is an early-stage B-Rep kernel, written in Rust. I think the project has a lot of potential, but of course being an early-stage project, it's not nearly as featureful as something like OpenCascade, which has had decades of development behind it.
+
+At the same time, I think Rust gives you the power to take on large ambitious projects and keep things organized, so if the maintainer can keep momentum and build a community of contributors behind the project, we may have a nice, pure-Rust solution to code-based CAD.
+
+For now though, I'd rather build a nice Rust API on top of OpenCascade, and then perhaps add Fornjot as a backend to that API when the project is farther along.