From 6c7ecd102d140c147bb600fb8ffb49c803601aa0 Mon Sep 17 00:00:00 2001
From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com>
Date: Fri, 12 Jul 2024 08:21:19 +1000
Subject: [PATCH] Update readme and docs with new features (#371)

* check readme in ci

* update docs

* Generate readme using rustdoc

* sign

* sign again
---
 .github/workflows/rust.yml | 11 +++++++++-
 CONTRIBUTING.md            | 28 +++++++++++++++++++++++++
 Makefile                   |  6 +++++-
 README.md                  | 43 +++++++++++++-------------------------
 src/lib.rs                 |  4 ++++
 5 files changed, 62 insertions(+), 30 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
index c892d9f2..a5a85a4c 100644
--- a/.github/workflows/rust.yml
+++ b/.github/workflows/rust.yml
@@ -13,7 +13,7 @@ jobs:
 
   complete:
     if: always()
-    needs: [generate, fmt, build, test, publish-dry-run]
+    needs: [generate, fmt, readme, build, test, publish-dry-run]
     runs-on: ubuntu-latest
     steps:
     - if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
@@ -37,6 +37,15 @@ jobs:
     - run: rustup update
     - run: cargo fmt --all --check
 
+  readme:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: stellar/actions/rust-cache@main
+    - run: rustup install nightly
+    - run: make readme
+    - run: git add -N . && git diff HEAD --exit-code
+
   build:
     strategy:
       matrix:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..86094042
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,28 @@
+# Contributing
+
+## How to Regenerate From XDR
+To regenerate types from XDR definitions:
+
+1. Update XDR definitions
+
+   ```console
+   git submodule update --init --remote
+   ```
+
+   The `--init` flag is only required for the first time setting up the local
+   project. `--remote` flag will make sure to fetch the latest changes from
+   from the remote-tracking branches `curr` and `next` at [stellar/stellar-xdr].
+
+   If you have multiple remotes specified in the submodules (e.g. one
+   *tracking `stellar/stellar-xdr`, the other tracking `your-fork/stellar-xdr`),
+   make sure the remote that tracks [stellar/stellar-xdr] match with what's
+   specifies in the `.git/config` or `.gitsubmodules` (with `.git/config` taking
+   precedence. If neither file specifies it, then `origin` is used).
+
+2. Recompile and test
+
+   ```console
+   make clean generate
+   ```
+
+   When the regenerated types are ready to be merged, make sure to commit the regenerated code file `src/curr/generated.rs`, `src/next/generated.rs`, the version string file `xdr/curr-version`, `xdr/next-version`, as well as the submodule files `xdr/curr`, `xdr/next`.
diff --git a/Makefile b/Makefile
index 5caee634..5f453f80 100644
--- a/Makefile
+++ b/Makefile
@@ -28,7 +28,11 @@ install:
 	cargo install --locked --path . --force --features cli
 
 readme:
-	cargo readme > README.md
+	cargo +nightly rustdoc -- -Zunstable-options -wjson \
+		&& echo '# stellar-xdr' \
+		| cat target/doc/stellar_xdr.json \
+		| jq -r '"# stellar-xdr\n\n" + .index[.root].docs' \
+		> README.md
 
 watch:
 	cargo watch --clear --watch-when-idle --shell '$(MAKE)'
diff --git a/README.md b/README.md
index bf8fa9fe..d46cb7ac 100644
--- a/README.md
+++ b/README.md
@@ -9,16 +9,16 @@ using [xdrgen].
 [stellar/stellar-xdr]: https://github.com/stellar/stellar-xdr
 [xdrgen]: https://github.com/stellar/xdrgen
 
-### Usage
+## Usage
 
-#### Library
+### Library
 To use the library, include in your toml:
 
 ```toml
 stellar-xdr = { version = "...", default-features = true, features = [] }
 ```
 
-##### Features
+#### Features
 
 The crate has several features, tiers of functionality, ancillary
 functionality, and channels of XDR.
@@ -47,7 +47,16 @@ Ancillary functionality:
 1. `base64` – Enables support for base64 encoding and decoding.
 2. `serde` – Enables support for serializing and deserializing types with
 the serde crate.
-3. `arbitrary` – Enables support for interop with the arbitrary crate.
+3. `serde_json` – Enables support for built-in functionality specifically
+for serde_json. Often not required to use the types with serde_json, and
+only necessary to use utility functions that depend on serde_json.
+4. `arbitrary` – Enables support for interop with the arbitrary crate.
+5. `hex` – Enables support for hex in string representations of some types.
+Automatically enabled when serde is enabled.
+6. `schemars` – Enables support for JSON Schema generation. (Experimental)
+
+Features marked experimental may disappear at anytime, see breaking changes
+at anytime, or and may be minimal implementations instead of complete.
 
 Channels of XDR:
 
@@ -58,7 +67,7 @@ If a single channel is enabled the types are available at the root of the
 crate. If multiple channels are enabled they are available in modules at
 the root of the crate.
 
-#### CLI
+### CLI
 
 To use the CLI:
 
@@ -66,7 +75,7 @@ To use the CLI:
 cargo install --locked stellar-xdr --version ... --features cli
 ```
 
-##### Examples
+#### Examples
 
 Parse a `TransactionEnvelope`:
 ```console
@@ -86,25 +95,3 @@ Parse a `BucketEntry` framed stream from a bucket file:
 ```console
 stellar-xdr decode --type BucketEntry --input stream-framed --output json-formatted bucket.xdr
 ```
-
-License: Apache-2.0
-
-
-### For Developers: How to Regenerate From XDR
-To regenerate types from XDR definitions
-1. Update XDR definitions
-```concole
-git submodule update --init --remote
-```
-The `--init` flag is only required for the first time setting up the local project. 
-`--remote` flag will make sure to fetch the latest changes from from the remote-tracking branches `curr` and `next` at [stellar/stellar-xdr]. 
-
-**_NOTE:_** if you had multiple remotes specified in the submodules (e.g. one tracking `stellar/stellar-xdr`, the other tracking `your-fork/stellar-xdr`),
-make sure the remote that tracks [stellar/stellar-xdr] match with what's specifies in the `.git/config` or `.gitsubmodules` (with `.git/config` taking precedence. If neither file specifies it, then `origin` is used).
-
-2. Recompile and test
-```console
-make
-```
-
-When the regenerated types are ready to be merged, make sure to commit the regenerated code file `src/curr/generated.rs`, `src/next/generated.rs`, the version string file `xdr/curr-version`, `xdr/next-version`, as well as the submodule files `xdr/curr`, `xdr/next`.
\ No newline at end of file
diff --git a/src/lib.rs b/src/lib.rs
index 3d9c5052..60583ea1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -59,6 +59,10 @@
 //! 4. `arbitrary` – Enables support for interop with the arbitrary crate.
 //! 5. `hex` – Enables support for hex in string representations of some types.
 //! Automatically enabled when serde is enabled.
+//! 6. `schemars` – Enables support for JSON Schema generation. (Experimental)
+//!
+//! Features marked experimental may disappear at anytime, see breaking changes
+//! at anytime, or and may be minimal implementations instead of complete.
 //!
 //! Channels of XDR:
 //!