Merge pull request #1836 from hannobraun/docs

Update crate-level documentation

README.md

@@ -19,6 +19,7 @@ Fornjot is supported by [**@webtrax-oz**](https://github.com/webtrax-oz), [**@re
 ## Table of Contents
 
 - [**Status**](#status)
+- [**Overview**](#overview)
 - [**Usage**](#usage)
 - [**Community**](#community)
 - [**Get Involved**](#get-involved)
@@ -30,6 +31,23 @@ Fornjot is supported by [**@webtrax-oz**](https://github.com/webtrax-oz), [**@re
 Fornjot is usable for some toy examples, but currently lacks the features for something more advanced. Work to change that is underway.
 
 
+## Overview
+
+This is a list of the crates that make up Fornjot, along with a short description for each, starting with the most basic ones and leading up to the high-level ones:
+
+- [`fj-math`]: Math primitives used by the rest of the Fornjot ecosystem.
+- [`fj-interop`]: Basic types that allow other crates to interoperate, without depending on each other.
+- [`fj-kernel`]: CAD kernel of Fornjot. Defines geometric and topological primitives, and algorithms that operate on those primitives.
+- [`fj-export`]: Exports Fornjot models to external data formats.
+- [`fj-viewer`]: Displays Fornjot models.
+
+[`fj-export`]: https://crates.io/crates/fj-export
+[`fj-interop`]: https://crates.io/crates/fj-interop
+[`fj-kernel`]: https://crates.io/crates/fj-kernel
+[`fj-math`]: https://crates.io/crates/fj-math
+[`fj-viewer`]: https://crates.io/crates/fj-viewer
+
+
 ## Usage
 
 This repository is currently [in flux](https://www.fornjot.app/blog/a-new-direction/) and the documentation previously available here no longer applies. This section will be updated in due time.

crates/README.md

@@ -1,36 +0,0 @@
-# Fornjot Crates
-
-## About
-
-Fornjot is both an application and an ecosystem of components that make up this application, but can be used independently. All if those components are located in this directory.
-
-If you're just looking to use Fornjot as a CAD program, don't worry about this directory. Check out [the website](https://www.fornjot.app/) or the [top-level `README.md`](../README.md).
-
-
-## Overview
-
-This is a list of the crates in this directory, along with a short description for each, starting with the most basic ones and leading up to the high-level ones most relevant to end users:
-
-- [`fj-math`]: Math primitives used by the rest of the Fornjot ecosystem.
-- [`fj-interop`]: Basic types that allow other crates to interoperate, without depending on each other.
-- [`fj-kernel`]: CAD kernel of Fornjot. Defines geometric and topological primitives, and algorithms that operate on those primitives.
-- [`fj-operations`]: CAD operations, built on top of `fj-kernel`. Link between the kernel, and the API that users use to define models.
-- [`fj-export`]: Exports Fornjot models to external data formats.
-- [`fj-host`]: Loads Fornjot models and watches them for changes.
-- [`fj-viewer`]: Displays Fornjot models.
-- [`fj-window`]: Embeds `fj-viewer` in a Winit-based window.
-- [`fj-app`]: The Fornjot CAD application.
-- [`fj-proc`]: Procedural macros to improve the usability of the `fj` crate.
-- [`fj`]: End-user API for defining Fornjot models.
-
-[`fj`]: https://crates.io/crates/fj
-[`fj-app`]: https://crates.io/crates/fj-app
-[`fj-export`]: https://crates.io/crates/fj-export
-[`fj-host`]: https://crates.io/crates/fj-host
-[`fj-interop`]: https://crates.io/crates/fj-interop
-[`fj-kernel`]: https://crates.io/crates/fj-kernel
-[`fj-math`]: https://crates.io/crates/fj-math
-[`fj-operations`]: https://crates.io/crates/fj-operations
-[`fj-proc`]: https://crates.io/crates/fj-proc
-[`fj-viewer`]: https://crates.io/crates/fj-viewer
-[`fj-window`]: https://crates.io/crates/fj-window

crates/fj-export/src/lib.rs

@@ -1,14 +1,10 @@
 //! # Fornjot Exporter
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
-//! code-first CAD application; and collection of libraries that make up the CAD
+//! split into multiple libraries that can be used semi-independently, and this
-//! application, but can be used independently.
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
+//! This library exports Fornjot models to external file formats.
-//! users that just want to create CAD models.
-//!
-//! The purpose of this library is to export Fornjot models to external file
-//! formats.
 //!
 //! [Fornjot]: https://www.fornjot.app/
 

crates/fj-interop/src/lib.rs

@@ -1,14 +1,11 @@
 //! # Fornjot Interop Types
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
-//! code-first CAD application; and collection of libraries that make up the CAD
+//! split into multiple libraries that can be used semi-independently, and this
-//! application, but can be used independently.
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
+//! This library defines types that allow other components of Fornjot to
-//! users that just want to create CAD models.
+//! interoperate, without having to depend on each other.
-//!
-//! The purpose of this library is to define types that allow other components
-//! of the Fornjot ecosystem to interoperate, without depending on each other.
 //!
 //! [Fornjot]: https://www.fornjot.app/
 

crates/fj-kernel/src/lib.rs

@@ -1,15 +1,11 @@
 //! # Fornjot CAD Kernel
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
-//! code-first CAD application; and collection of libraries that make up the CAD
+//! split into multiple libraries that can be used semi-independently, and this
-//! application, but can be used independently.
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
+//! This library defines geometric and topological primitives, and the
-//! users that just want to create CAD models.
+//! algorithms that operate on them.
-//!
-//! The CAD kernel is the core of Fornjot: the geometry, the topology, and the
-//! algorithms that handle them. It is separate from the CAD application, and
-//! could be used in other applications.
 //!
 //!
 //! ## Design Principle

crates/fj-math/src/lib.rs

@@ -1,16 +1,14 @@
 //! # Fornjot Math Library
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
-//! code-first CAD application; and collection of libraries that make up the CAD
+//! split into multiple libraries that can be used semi-independently, and this
-//! application, but can be used independently.
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
+//! This library provides basic math types for Fornjot. It is built on
-//! users that just want to create CAD models.
+//! [nalgebra] and [Parry], but provides an interface that is specifically
-//!
-//! This crates provides basic math types for the Fornjot ecosystem. It is built
-//! on [nalgebra] and [Parry], but provides an interface that is specifically
 //! tailored to the needs of Fornjot.
 //!
+//!
 //! ## Failing [`From`]/[`Into`] implementations
 //!
 //! Please note that any [`From`]/[`Into`] implementation that convert floating

crates/fj-viewer/src/lib.rs

@@ -1,14 +1,10 @@
 //! # Fornjot Model Viewer
 //!
-//! This library is part of the [Fornjot] ecosystem. Fornjot is an open-source,
+//! [Fornjot] is an early-stage b-rep CAD kernel written in Rust. The kernel is
-//! code-first CAD application; and collection of libraries that make up the CAD
+//! split into multiple libraries that can be used semi-independently, and this
-//! application, but can be used independently.
+//! is one of those.
 //!
-//! This library is an internal component of Fornjot. It is not relevant to end
+//! This library provides a viewer for Fornjot models.
-//! users that just want to create CAD models.
-//!
-//! This library provides a model viewer which allows basic navigation and
-//! rendering of generated models.
 //!
 //! [Fornjot]: https://www.fornjot.app/