Merge pull request #46 from Bromeon/bugfix/cleanup

Consistency and formatting cleanup + Projects chapter

Author: Bromeon

README.md

@@ -19,10 +19,12 @@ $ mdbook serve
 
 This repository is for documentation only. Please make pull requests for the library itself in the [main repo](https://github.com/godot-rust/godot-rust).
 
+
 ## Contributing
 
 See the [contribution guidelines]([CONTRIBUTING.md](https://github.com/godot-rust/godot-rust/blob/book/CONTRIBUTING.md)) in the main repo.
 
+
 ## License
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed under the [MIT license](LICENSE.md), without any additional terms or conditions.
+Any contribution intentionally submitted for inclusion in the work by you shall be licensed under the [MIT license](LICENSE.md), without any additional terms or conditions.

src/SUMMARY.md

@@ -14,26 +14,30 @@
     - [Exported properties](./rust-binding/properties.md)
     - [Calling into GDScript from Rust](./rust-binding/calling-gdscript.md)
 - [FAQ](./faq.md)
-  - [Code Questions](./faq/code.md)
-  - [Multithreading](./faq/multithreading.md)
-  - [Configuration](./faq/configuration.md)
-  - [Versioning and supported platforms](./faq/meta.md)
-  - [Community](./faq/community.md)
-  - [Godot 4.0 Status](./faq/godot4.md)
+    - [Common code questions](./faq/code.md)
+    - [Multithreading](./faq/multithreading.md)
+    - [Configuration](./faq/configuration.md)
+    - [Versioning and supported platforms](./faq/support.md)
+    - [Community](./faq/community.md)
+    - [Godot 4.0 Status](./faq/godot4.md)
 - [(TODO) Testing](./testing.md)
-    - [Structuring Code for Testing](./testing/structure.md)
-    - [Testing with the Engine](./testing/engine.md)
+    - [Structuring code for testing](./testing/structure.md)
+    - [Testing with the engine](./testing/engine.md)
 - [Recipes](./recipes.md)
-    - [Rust Panic Hook](./recipes/rust_panic_handler.md)
+    - [Async with Tokio runtime](./recipes/async-tokio.md)
+    - [Custom node plugin](./recipes/custom-node-plugin.md)
+    - [Loading external resources](./recipes/external-resources.md)
     - [Logging](./recipes/logging.md)
-    - [Loading external resources](./recipes/loading_external_resources.md)
-    - [Custom nodes Plugin](./recipes/custom-nodes-plugin.md)
-	- [Tokio Runtime](./recipes/tokio_runtime.md)
+    - [Nix as development environment](recipes/nix-build-system.md)
+    - [Rust panic handler](./recipes/panic-handler.md)
+- [Third-party projects](./projects.md)
+    - [Games](./projects/games.md)
+    - [Tools and integrations](./projects/tools.md)
+    - [Applications](./projects/applications.md)
 - [Exporting](./exporting.md)
     - [Android](./exporting/android.md)
     - [(TODO) iOS](./exporting/ios.md)
     - [Mac OS X](./exporting/macosx.md)
 - [Advanced Guides](./advanced-guides.md)
-    - [Using custom builds of Godot](./advanced-guides/custom-bindings.md)
-    - [Nix as A Development Environment](./advanced-guides/nix-build-system.md)
-- [Migrating from godot-rust 0.8.x](./migrating-0-8.md)
+    - [Using custom Godot versions](./advanced-guides/custom-godot.md)
+    - [Migrating from godot-rust 0.8](advanced-guides/migrating-0-8.md)

src/advanced-guides/custom-bindings.md renamed to src/advanced-guides/custom-godot.md

@@ -37,7 +37,8 @@ If everything goes well, you can now update the dependencies of your GDNative li
 ```toml
 [dependencies]
 
-# Use the exact version corresponding to `gdnative-bindings`, and disable the default re-export.
+# Use the exact version corresponding to `gdnative-bindings`
+# and disable the default re-export.
 gdnative = { version = "=0.9.0", default-features = false, features = [] }
 
 # Use your custom bindings crate as a path dependency
@@ -48,6 +49,7 @@ Here, `gdnative` is specified using an exact version because the bindings genera
 
 Finally, replace references to `gdnative::api` with `gdnative-bindings-custom`. You should now be able to use the APIs in your custom build in Rust!
 
+
 ## Generating documentation
 
 However, if you try to generate documentation with rustdoc at this point, you might notice that documentation might be missing or wrong for some of the types or methods. This is due to documentation being stored separately from the API description itself, and can be easily fixed if you have access to the source code from which your custom Godot binary is built.

src/migrating-0-8.md renamed to src/advanced-guides/migrating-0-8.md

@@ -1,7 +1,8 @@
-# Migrating from godot-rust 0.8.x
+# Migrating from godot-rust 0.8
 
 In version 0.9, we are attempting to resolve many long-standing problems in the older API. As a result, there are many breaking changes in the public interface. This is a quick guide to the new API for users that have used older versions.
 
+
 ## Module organization and naming
 
 ### Generated API types
@@ -60,6 +61,7 @@ object.connect("foo", owner, "_handle_foo", VariantArray, ConnectFlags::DEFERRED
 
 Typos in variant names of `VariantOperator` and `GodotError` are fixed. Change to the correct names if this breaks your code.
 
+
 ## Changes to derive macros
 
 The `NativeScript` derive macro now looks for `new` instead of `_init` as the constructor.
@@ -95,6 +97,7 @@ impl Thing {
 }
 ```
 
+
 ## Argument casts
 
 Generated methods taking objects, `Variant`, and `GodotString` are now made generic using `impl Trait` in argument position. This make calls much less verbose, but may break inference for some existing code. If you have code that looks like:
@@ -139,6 +142,7 @@ thing.set_script(Null::null());
 
 This is arguably less convenient, but passing explicit nulls should be rare enough a use case that the benefits of having polymorphic arguments are much more significant.
 
+
 ## Object semantics
 
 In 0.9, the way Godot objects are represented in the API is largely remodeled to closely match the behavior of Godot. For the sake of illustration, we'll use the type `Node` in the following examples.
@@ -284,6 +288,7 @@ where
 }
 ```
 
+
 ## Casting
 
 The casting API is made more convenient with 0.9, using the `SubClass` trait. Casting is now covered by two generic methods implemented on all object reference types: `cast` and `upcast`. Both methods enforce cast validity statically, which means that the compiler will complain about casts that will always fail at runtime. The generated `to_*` methods are removed in favor of `upcast`.
@@ -329,6 +334,7 @@ where
 
 Note that this function is also polymorphic over the `Access` typestate, which is explained the the following section.
 
+
 ## Typestates
 
 The typestate pattern is introduced in 0.9 to statically provide fine-grained reference safety guarantees depending on thread access state. There are three typestates in the API:

src/before.png

@@ -4,6 +4,7 @@
 
 In order to export to Android, we need to compile our Rust source for the appropriate targets. Unlike compiling for our native targets, there are a few extra steps involved with cross-compiling for another target.
 
+
 ## Installing prerequisites
 
 First, we need to install the **Android SDK** with **NDK** enabled. This contains the necessary tools for each architecture. Once the Android SDK is installed, open Editor Settings in the Godot GUI (*Editor > Editor Settings > Export > Android*) and set the **absolute paths** to `adb`, `jarsigner`, and the debug keystore (`debug.keystore`), all of which can be found in the Android SDK installation.
@@ -47,6 +48,7 @@ apt-get update
 apt-get install g++-multilib gcc-multilib libc6-dev-i386 -y
 ```
 
+
 ## Setting up Cargo
 
 To make Cargo aware of the proper platform-specific linkers that it needs to use for Android targets, we need to put the paths to the binaries in the Cargo configuration file, which can be found (or created) at `$HOME/.cargo/config` on UNIX-like systems, or `%USERPROFILE%\.cargo\config` on Windows), using [`[target]` tables](https://doc.rust-lang.org/cargo/reference/config.html#target):
@@ -79,6 +81,7 @@ linker = "/usr/local/lib/android/sdk/ndk-bundle/toolchains/llvm/prebuilt/linux-x
 linker = "/usr/local/lib/android/sdk/ndk-bundle/toolchains/llvm/prebuilt/linux-x86_64/bin/x86_64-linux-android29-clang"
 ```
 
+
 ## Setting up environment variables for `gdnative-sys`
 
 The `gdnative-sys` crate can infer include paths for Android targets, but it requires the following environment variables:
@@ -100,6 +103,7 @@ $env:JAVA_HOME = "C:\path\to\jdk"
 $env:ANDROID_SDK_ROOT = "C:\path\to\android\sdk"
 ```
 
+
 ## Building the GDNative library
 
 Finally, we can now build the GDNative library with Cargo for one or multiple targets:
@@ -110,6 +114,7 @@ cargo build --release --target x86_64-linux-android
 
 **Important note**: ARM and x86 are, by design, different architectures. It is normal to get errors while running `cargo test` with a Rust library targeting ARMv7 on a x86-64 CPU, for example, since the CPU is unable to handle it.
 
+
 ## Exporting in Godot
 
 ### Linking to Android binaries in `.gdns`

src/exporting/android.md

@@ -2,6 +2,7 @@
 
 **Disclaimer**: _Currently, the following steps are tested and confirmed to work on Linux only._
 
+
 ## Use case
 
 Exporting for Mac OS X is interesting if:
@@ -11,6 +12,7 @@ Exporting for Mac OS X is interesting if:
 
 If you have access to a real Mac, building natively is easier.
 
+
 ## Why is this complex ?
 
 Cross-compiling Rust programs for Mac OS X is as simple as:
@@ -116,6 +118,7 @@ As a consequence, you do *not* need to put `$MACOSX_CROSS_COMPILER/cross-compile
 you only plan to export [godot-rust](https://github.com/godot-rust/godot-rust) based programs, as the
 binary needs to be explicitly overloaded.
 
+
 ## Exporting
 
 Once your `.dylib` file is built, a standard Godot export should work:
@@ -131,6 +134,7 @@ folder, ready to use.
 
 Double-check your `.dylib` file is there.
 
+
 ## Useful links
 
 * https://github.com/tpoechtrager/osxcross : tool used to install the Mac OS X SDK on Linux

src/exporting/macosx.md

@@ -1,4 +1,4 @@
-# Common Code Questions
+# FAQ: Common code questions
 
 ## What is the `BorrowFailed` error and why do I keep getting it?
 
@@ -261,6 +261,7 @@ While a similar case applies for [`ShaderMaterial`](https://docs.rs/gdnative/lat
 
 Direct access to such properties is planned in [godot-rust/godot-rust#689](https://github.com/godot-rust/godot-rust/issues/689).
 
+
 ## What is the godot-rust equivalent of `preload`?
 
 Unfortunately, there is no equivalent to preload in languages other than GDScript, because preload is GDScript-specific magic that works at compile time. If you read the official documentation on preload, it says:
@@ -275,6 +276,7 @@ The ResourceLoader should be used in most cases.
 
 Also, you can always put a Mutex<HashMap> into a Rust static and load everything you need there during a loading screen.
 
+
 ## How do I keep a reference of `Node`?
 
 The idiomatic way to maintain a reference to a node in the SceneTree from Rust is to use `Option<Ref<T>>`. 
@@ -315,6 +317,7 @@ Note: As `TRef<T>` is a temporary pointer, it will be necessary to get the base
 
 This can be done with the [`TRef<T>::claim()`](https://docs.rs/gdnative/latest/gdnative/struct.TRef.html#method.claim) function that will return the persistent version of the pointer that you can store in your class.
 
+
 ## What is the Rust equivalent to `onready var` in GDScript
 
 Rust does not have a direct equivalent to `onready var`. The most idiomatic workaround with Rust is to use `Option<Ref<T>>` of you need the Godot node type or `Option<Instance<T>>` if you are using a Rust based `NativeClass`.
@@ -375,6 +378,7 @@ Some concrete examples of types that can be used with the GDNative API are the f
 - Godot classes such as `Node`, `Reference`, etc. which must be accessed via [`Ref<T>`](https://docs.rs/gdnative/latest/gdnative/struct.Ref.html) (you can't pass them by value, because Godot owns them).
 - Any Rust struct that derives [`NativeClass`](https://docs.rs/gdnative/latest/gdnative/derive.NativeClass.html) through [`Instance<T>`](https://docs.rs/gdnative/latest/gdnative/nativescript/struct.Instance.html).
 
+
 ## How can I profile my code to determine the performance?
 
 There are a lot of ways to profile your code and they will vary in complexity.

src/faq/code.md

@@ -1,4 +1,4 @@
-# Community FAQ
+# FAQ: Community
 
 ## I need help, where can I ask?
 

src/faq/community.md

@@ -1,21 +1,23 @@
-# Configuration
+# FAQ: Configuration
 
 ## How do I create the library file for my GDNative binary?
 
 You can create .gdnlib files with either of the following methods.
 
-### Editor 
-1. In the editor, right click in the File System and Select "New Resource" 
-2. Select GDNativeLibrary from the menu.
+### Editor
+
+1. In the editor, right click in the File System and Select _New Resource_. 
+2. Select _GDNativeLibrary_ from the menu.
 3. Save as new GDNativeLibrary. The typical file extension is `.gdnlib`.
 4. Select the GDNativeLibrary.
-5. For each desired target, select a path to the location of the library created by cargo.
+5. For each desired target, select a path to the location of the library created by Cargo.
 
 ### Manual
-Create a text file with the .gdnlib extension with the following content.
+
+Create a text file with the `.gdnlib` extension with the following content.
 Please note: you only need to include paths for the targets you plan on building for.
 
-```
+```toml
 [entry]
 X11.64="res://path/to/lib{name_of_binary}.so"
 OSX.64="res://path/to/lib{name_of_binary}.dylib"
@@ -33,13 +35,14 @@ symbol_prefix="godot_"
 reloadable=true
 ```
 
-## Once I create the .gdnlib file, how do I create the GDNative Script so that I can attach it to the nodes in the scene tree?
+
+## Once I create the `.gdnlib` file, how do I create the native script, so that I can attach it to the nodes in the scene tree?
 
 Script files can be created in two ways.
 
 1. From the editor.
-2. Manually by creating a .gdns file with the following code snippet.
-```
+2. Manually by creating a `.gdns` file with the following code snippet.
+```toml
 [gd_resource type="NativeScript" load_steps=2 format=2]
 
 [ext_resource path="res://path/to/{name of file}.gdnlib" type="GDNativeLibrary" id=1]
@@ -48,16 +51,17 @@ Script files can be created in two ways.
 resource_name = "{class name}"
 class_name = "{class name}"
 library = ExtResource( 1 )
-
 ```
 
-## Why aren't my scripts showing up in the Add Node portion of the editor even though they inherit from  `Node`, `Node2D`, `Spatial` or `Control`?
 
-Due to limitations with Godot 3.x's version of GDNative, NativeScript types do not get registered in the class database. As such, these classes are not included in the "Create New Node" dialog.
+## Why aren't my scripts showing up in the _Add Node_ portion of the editor, even though they inherit from  `Node`, `Node2D`, `Spatial` or `Control`?
+
+Due to limitations with Godot 3.x's version of GDNative, NativeScript types do not get registered in the class database. As such, these classes are not included in the _Create New Node_ dialog.
 
-A workaround to this issue has been included in the recipe [Custom Nodes Plugin](../recipes/custom-nodes-plugin.md).
+A workaround to this issue has been included in the recipe [Custom Nodes Plugin](../recipes/custom-node-plugin.md).
 
-## Can I use Rust for a [toolscript](https://docs.godotengine.org/en/stable/tutorials/misc/running_code_in_the_editor.html)?
+
+## Can I use Rust for a [tool script](https://docs.godotengine.org/en/stable/tutorials/misc/running_code_in_the_editor.html)?
 
 Yes, any Rust struct that inherits from `NativeClass` can be also used as a tool class by using the `InitHandle::add_tool_class` during native script initialization instead of `InitHandle::add_class`.
 
@@ -84,6 +88,7 @@ Please also see the [native_plugin](https://github.com/godot-rust/godot-rust/tre
 - Editor plugins do not support the hot reload feature. If making use of tool classes, your `GDNativeLibrary` must have `reloadable=false` or the plugins will crash when the editor loses focus.
 - It is advised that `GDNativeLibrary` files for editor plugins be compiled as a separate "cdylib" from the `GDNativeLibrary` that may need to be recompiled during development, such as game logic.
 
+
 ## Is it possible to use multiple libraries with GDNative?
 
 Yes. This is possible, but it should be avoided unless necessary. Generally you should create one `GDNativeLibrary` (`.gdnlib`) and associate many `NativeScript` (`.gdns`) files with the single library.
@@ -94,7 +99,7 @@ If you do have a scenario that requires multiple `GDNativeLibrary`, you can crea
 
 To avoid these collisions, rather than the `godot_init!` initialization macro, prefer the use of the individual macros.
 
-For example, if we want to define the symbol_prefix for our library "my_symbol_prefix" we can use the macros below.
+For example, if we want to define the symbol_prefix for our library "my_symbol_prefix", we can use the macros below.
 
 ```rust
 // _ indicates that we do not have any specific callbacks needed from the engine for initialization. So it will automatically create
@@ -108,24 +113,24 @@ godot_nativescript_init!(registration_function as my_symbol_prefix_nativescript_
 godot_gdnative_terminate!(_ as my_symbol_prefix_gdnative_terminate);
 ```
 
-## Can I expose {insert rust crate name} for use with Godot and GDScript?
+## Can I expose {insert Rust crate name} for use with Godot and GDScript?
 
-Yes, with NativeScript so long as you can create a `NativeScript` wrapper you can create GDScript bindings for a rust crate. See the [logging recipe](../recipes/logging.md) for an example of wrapping a Rust logging crate for use with GDScript.
+Yes, with NativeScript so long as you can create a `NativeScript` wrapper you can create GDScript bindings for a Rust crate. See the [logging recipe](../recipes/logging.md) for an example of wrapping a Rust logging crate for use with GDScript.
 
 
-## How do I get code Auto-completion with rust-analyzer?
+## How do I get auto-completion with rust-analyzer?
 
 `godot-rust` generates most of the gdnative type's code at compile-time. Editors using [rust-analyzer](https://github.com/rust-analyzer/rust-analyzer) struggle to autocomplete those types:
 
-![no-completion](../images/no-completion.png)
+![no-completion](img/no-completion.png)
 
 
 People [reported](https://github.com/rust-analyzer/rust-analyzer/issues/5040) similar issues and found that switching on the `"rust-analyzer.cargo.loadOutDirsFromCheck": true` setting fixed it:
 
-![completion](../images/completion.png)
+![completion](img/completion.png)
 
 
-## How do I get code Auto-completion with IntelliJ Rust Plugin
+## How do I get auto-completion with IntelliJ-Rust plugin?
 
 Similar to rust-analyzer, IntelliJ-Family IDEs struggle to autocomplete gdnative types generated at compile-time.
 
@@ -138,6 +143,7 @@ Second, the bindings files generated (~8mb) are above the 2mb limit for files to
 * add `-Didea.max.intellisense.filesize=limitValue` line where `limitValue` is desired limit in KB, for example, 10240. Note, it cannot be more than 20 MB.
 * restart IDE
 
+
 ## How can I make my debug builds more performant?
 
 **Note**: These changes may slow down certain aspects of the build times for your game.