Documentation part II (#116)

This PR fleshes out the documentation book. It should be fairly readable in Markdown in the github interface, but may be better done in mdbook. Note to self: document how to contribute to documents.
jhugman · Oct 8, 2024 · 3891cab · 3891cab
1 parent f0a45f5
commit 3891cab
Show file tree

Hide file tree

Showing 33 changed files with 1,072 additions and 156 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,25 @@
+# Community Participation Guidelines
+
+This repository is governed by Mozilla's code of conduct and etiquette guidelines.
+For more details, please read the
+[Mozilla Community Participation Guidelines](https://www.mozilla.org/about/governance/policies/participation/).
+
+## How to Report
+For more information on how to report violations of the Community Participation Guidelines, please read our '[How to Report](https://www.mozilla.org/about/governance/policies/participation/reporting/)' page.
+
+## Project Specific Etiquette
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+Project maintainers who do not follow or enforce Mozilla's Participation Guidelines in good
+faith may face temporary or permanent repercussions.
diff --git a/README.md b/README.md
@@ -1,6 +1,35 @@
 # uniffi-bindgen-react-native
-A uniffi bindings generator for calling Rust from react-native
+[UniFFI](https://mozilla.github.io/uniffi-rs/latest/) is a multi-language bindings generator for Rust.
 
+This project, `uniffi-bindgen-react-native`, is a uniFFI bindings generator for using Rust from React Native.
+
+It provides tooling to generate:
+
+- Typescript and JSI C++ to call Rust from Typescript and back again
+- a Turbo-Module that installs the bindings into a running React Native library.
+
+If you're ready to start, then start with [a step-by-step tutorial to make a Rust turbo-module](https://jhugman.github.io/uniffi-bindgen-react-native/).
+
+If you're new to uniFFI, then [**the UniFFI user guide**](https://mozilla.github.io/uniffi-rs/latest/)
+or [**the UniFFI examples**](https://github.com/mozilla/uniffi-rs/tree/main/examples#example-uniffi-components) are interesting places to start.
+
+## Contributing
+
+If this tool sounds interesting to you, please help us develop it! You can:
+
+* View the [contributor guidelines](./docs/contributing.md).
+* File or work on [issues](https://github.com/jhugman/uniffi-bindgen-react-native/issues) here in GitHub.
+<!--
+* Join discussions in the [#uniffi:mozilla.org](https://matrix.to/#/#uniffi:mozilla.org) room on Matrix.
+-->
+
+## Code of Conduct
+
+This project is governed by Mozilla's [Community Participation Guidelines](./CODE_OF_CONDUCT.md).
+
+## Funding
+
+`uniffi-bindgen-react-native` is lead by James Hugman, with deep collaboration from the [Filament](https://filament.im) engineering team, funded by [Filament](https://filament.im) and [Mozilla](https://future.mozilla.org).
 
 ## License
 

diff --git a/docs/book.toml b/docs/book.toml
@@ -51,14 +51,14 @@ cache-timeout = 43200
 # - "error" treats all warnings as errors, failing the linkcheck
 # - "ignore" will ignore warnings, suppressing diagnostic messages and allowing
 #   the linkcheck to continuing
-warning-policy = "warn"
+warning-policy = "error"
 
 [output.html]
 smart-punctuation = true
 mathjax-support = false
 site-url = "/mdBook/"
-git-repository-url = "https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/docs/"
-edit-url-template = "https://github.com/jhugman/uniffi-bindgen-react-native/edit/main/docs/{path}"
+git-repository-url = "https://github.com/jhugman/uniffi-bindgen-react-native"
+edit-url-template = "edit/main/docs/{path}"
 
 # open on gh config.
 git-branch = "main"

diff --git a/docs/mismatch/enums.md b/docs/mismatch/enums.md
diff --git a/docs/mismatch/records.md b/docs/mismatch/records.md
diff --git a/docs/src/README.md b/docs/src/README.md
@@ -8,6 +8,15 @@ It has since grown to support for other languages not in use at Mozilla.
 
 [`uniffi-bindgen-react-native`](https://github.com/jhugman/uniffi-bindgen-react-native) is the project that houses the bindings generators for react-native.
 
+It supports all language features that `uniffi-rs` supports, including:
+
+- calling functions from Typescript to Rust, synchronous and asynchronous.
+- calling functions from Rust to Typescript, synchronous and asynchronous.
+- objects with methods, including:
+    - garbage collection integration.
+    - uniffi traits
+- custom types
+
 It contains tooling to generate bindings from Hermes via JSI, and to generate the code to create turbo-modules.
 
 ```admonish warning

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -2,12 +2,35 @@
 
 [Introduction](README.md)
 
-* [Getting Started](getting-started/README.md)
-    - [Before you start](getting-started/pre-installation.md)
-    - [Step by step: Make your first library project](getting-started/guide.md)
-
-* [Reference](api/README.md)
-    - [Command Line](api/commandline.md)
-    - [Configuring your project](api/config-yaml.md)
-    - [Tweaking code generation](api/uniffi-toml.md)
-    - [Generating a Turbo Module](api/turbo-module-files.md)
+# Getting started
+
+- [Before you start](getting-started/pre-installation.md)
+- [Step by step: Make your first library project](getting-started/guide.md)
+
+# Mapping Rust on to Typescript
+
+- [Common types](idioms/common-types.md)
+- [Objects: Objects with methods](idioms/objects.md)
+  - [Garbage Collection and the Drop trait](idioms/gc.md)
+- [Records: Objects without methods](idioms/records.md)
+- [Enums and Tagged Unions](idioms/enums.md)
+- [Errors](idioms/errors.md)
+- [Callback interfaces]()
+- [Promises/Futures](idioms/promises.md)
+- [Async Callback interfaces]()
+
+# Contributing
+
+- [Local development](contributing/local-development.md)
+- [Adding or changing generated turbo-module templates](contributing/changing-turbo-module-templates.md)
+- [Changing generated Typescript or C++ templates](contributing/changing-bindings-templates.md)
+- [Cutting a Release](./contributing/cutting-a-release.md)
+
+# Reference
+
+- [`ubrn` Command Line](reference/commandline.md)
+- [`ubrn.config.yaml`](reference/config-yaml.md)
+- [`uniffi.toml`](reference/uniffi-toml.md)
+- [Generating a Turbo Module](reference/turbo-module-files.md)
+- [Reserved words](reference/reserved-words.md)
+- [Potential collisions](reference/potential-collisions.md)
diff --git a/docs/src/api/README.md b/docs/src/api/README.md
diff --git a/docs/src/contributing/changing-bindings-templates.md b/docs/src/contributing/changing-bindings-templates.md
@@ -0,0 +1,39 @@
+# Changing generated Typescript or C++ templates
+
+The central workings of a `uniffi-bingen` are its templates.
+
+`uniffi-bindgen-react-native` templates are in the following directories:
+
+- [Typescript templates][ts-templates]
+- [C++ templates][cpp-templates]
+
+Templates are written for [Askama templating library](https://djc.github.io/askama/template_syntax.html).
+
+There is a small-ish runtime for both languages:
+
+- [`typescript/src`][ts-runtime], with [tests][ts-tests] and [polyfills][ts-polyfills].
+- ['cpp/includes`][cpp-runtime].
+
+This is intended to allow developers from outside the project to contribute more easily.
+
+Making a change to the templates should be accompanied by an additional test, either in [an existing test fixture][fixtures], or a new one.
+
+Running the tests can be done with:
+
+```sh
+./scripts/run-tests.sh
+```
+
+An individual test can be run:
+
+```sh
+./scripts/run-tests.sh -f $fixtureName
+```
+
+[ts-templates]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/crates/ubrn_bindgen/src/bindings/react_native/gen_typescript/templates
+[cpp-templates]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/crates/ubrn_bindgen/src/bindings/react_native/gen_cpp/templates
+[ts-runtime]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/typescript/src
+[ts-tests]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/typescript/tests
+[ts-polyfills]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/typescript/testing
+[cpp-runtime]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/cpp/includes
+[fixtures]: https://github.com/jhugman/uniffi-bindgen-react-native/tree/main/fixtures
diff --git a/docs/src/contributing/changing-turbo-module-templates.md b/docs/src/contributing/changing-turbo-module-templates.md
@@ -0,0 +1,25 @@
+# Adding or changing turbo-module templates
+
+In addition to generating the bindings between Hermes and Rust, `uniffi-bindgen-react-native` generates the files needed to run this as a turbo-module. The list of files are [documented elsewhere in this book](../reference/turbo-module-files.md).
+
+Templates are written for [Askama templating library](https://djc.github.io/askama/template_syntax.html).
+
+Changing the templates for these files is relatively simple. [This PR is a good example](https://github.com/jhugman/uniffi-bindgen-react-native/pull/112) of adding a file.
+
+- Template files are in the [`codegen/templates` directory][codegen/templates].
+- Template configuration are in [`codegen/mod.rs`][codegen/mod.rs] file.
+
+[codegen/mod.rs]: https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/mod.rs
+[codegen/templates]: https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/codegen/templates
+
+### Adding a new template
+
+1. Add new template to the [`codegen/templates` directory][codegen/templates].
+1. Add a new `RenderedFile` struct, which specifies the template, and its path to [the `files` module](https://github.com/jhugman/uniffi-bindgen-react-native/blob/e7f85c616bf6985070081ec47f0b2b268890cc7d/crates/ubrn_cli/src/codegen/mod.rs#L141-L298) in [`codegen/mod.rs`][codegen/mod.rs].
+1. Add an entry to [the list of generated files in this book](../reference/turbo-module-files.md).
+
+The [template context](https://github.com/jhugman/uniffi-bindgen-react-native/blob/e7f85c616bf6985070081ec47f0b2b268890cc7d/crates/ubrn_cli/src/codegen/mod.rs#L55-L59) will have quite a lot of useful information data-structures about the project; the most prominent:
+
+- [`ModuleMetadata`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_bindgen/src/bindings/metadata.rs), which is generated from the `lib.a` file from the uniffi contents of the Rust library.
+- [`ProjectConfig`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_cli/src/config/mod.rs) which is the in-memory representation of the [YAML configuration file](../reference/config-yaml.md).
+- [`CrateMetadata`](https://github.com/jhugman/uniffi-bindgen-react-native/blob/main/crates/ubrn_common/src/rust_crate.rs) which is data about the crate derived from `cargo metadata`.
diff --git a/docs/src/contributing/cutting-a-release.md b/docs/src/contributing/cutting-a-release.md
@@ -0,0 +1,16 @@
+# Cutting a Release
+
+## Version numbers
+
+Uniffi has a `semver` versioning scheme. At time of writing, the current version of `uniffi-rs` is `0.28.3`
+
+`uniffi-bindgen-react-native` uses this version number with prepended with a `-` and a variant number, starting at `0`.
+
+Thus, at first release, the version of `uniffi-bindgen-react-native` will be `0.28.3-0`.
+
+### Compatibility with other packages
+
+Other versioning we should take care to note:
+
+- React Native
+- `create-react-native-library`