Improve documentation in top-level and subproject READMEs

README.md

@@ -1,51 +1,32 @@
 # Bisq API Reference Doc Generator
 
-[Produces Bisq API Reference Doc.](https://bisq-network.github.io/slate)
+Generates content for the [Bisq API Reference](https://bisq-network.github.io/slate) site.
 
 ## What is bisq-api-reference?
 
-This application script consumes Bisq .proto files (`pb.proto` and `grpc.proto`), and produces
+This project's main purpose is to generate the Markdown text for
-`index.html.md` -- a [Slate](https://github.com/slatedocs/slate) compatible Markdown file.
+the [API Reference](https://bisq-network.github.io/slate). It also provides a Java and Python workarea for running API
+client example code, and developing new Java and Python clients and bots.
 
-The Markdown file is then manually deployed to a developer's or bisq-network's fork of the
+It contains four subprojects:
-[Slate repository](https://github.com/slatedocs/slate), where the slate fork transforms it to a single html file
-describing Bisq gRPC API services, with example code.
-
-## Usage
-
-1. [Fork Slate](https://github.com/slatedocs/slate)
-
-
-2. Run `BisqApiDocMain`:
-
-```asciidoc
-BisqApiDocMain --protosIn=<path-to-bisq-protub-files>/proto 
-            \ --markdownOut=<path-to-slate-home>/source 
-            \ --failOnMissingDocumentation=false
-```
-
-3. Commit changes in your local slate/source file (`index.html.md`) _to your forked slate repo_.
-
-```asciidoc
-git commit -a -m "Update index.html.md"
-```
-
-4. Run slate's `deploy.sh` script
-
-
-5. After a few minutes, see changes on in your forked slate's github pages site. For example,</br>
-   if your `index.html.md` file was deployed to bisq-network, the URL will be
-   https://bisq-network.github.io/slate.
-
-
-## Credits
-
-Credit to [Juntao Han](https://github.com/mstao) for making his [markdown4j](https://github.com/mstao/markdown4j)
-API available for use in this project.  His source code is included in this project, modified in ways to make
-generated markdown blocks compatible with Slate/GitHub style markdown.
-
-Lombok annotations are also replaced by the implementations they would generate if that had worked in my
-gradle development setup.
 
+1. [reference-doc-builder](https://github.com/ghubstan/bisq-api-reference/tree/main/reference-doc-builder) -- The Java
+   application that produces the [API Reference](https://bisq-network.github.io/slate) content, from Bisq protobuf
+   definition files.
+2. [cli-examples](https://github.com/ghubstan/bisq-api-reference/tree/main/cli-examples) -- A folder of bash scripts
+   demonstrating how to run API CLI commands. Each script is named for the RPC method call being demonstrated.
+3. [java-examples](https://github.com/ghubstan/bisq-api-reference/tree/main/java-examples) -- A Java project
+   demonstrating how to call the API from Java gRPC clients. Each class in
+   the [bisq.rpccalls](https://github.com/ghubstan/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls)
+   package is named for the RPC method call being demonstrated.
+4. [python-examples](https://github.com/ghubstan/bisq-api-reference/tree/main/python-examples) -- A Python3 project
+   demonstrating how to call the API from Python3 gRPC clients. Each class in
+   the  [bisq.rpccalls](https://github.com/ghubstan/bisq-api-reference/tree/main/python-examples/bisq/rpccalls) package
+   is named for the RPC method call being demonstrated. There are also some simple bot examples in
+   the [bisq.bots](https://github.com/ghubstan/bisq-api-reference/tree/main/python-examples/bisq/bots) package.
 
+The RPC method examples are also displayed in the [API Reference](https://bisq-network.github.io/slate). While
+navigating the RPC method links in the reference's table of contents on the left side of the page, they appear in the
+dark, right side of the page. There is also a copy-to-clipboard icon at the top right of each example.
 
+More details about the subprojects can be found in each subproject's README.

cli-examples/README.md

@@ -0,0 +1,7 @@
+# Bisq API CLI Examples
+
+This subproject contains bash scripts demonstrating API CLI command usage.
+
+Each script is named for the RPC method call being demonstrated in the script.
+
+

java-examples/README.md

@@ -0,0 +1,11 @@
+# Bisq API Java Examples
+
+This subproject contains Java classes demonstrating API gRPC method calls.
+
+Each class in
+the [bisq.rpccalls](https://github.com/ghubstan/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls)
+package is named for the RPC method call being demonstrated.
+
+The subproject uses a
+a [Gradle build file](https://github.com/ghubstan/bisq-api-reference/blob/main/java-examples/build.gradle), also
+demonstrating how to generate the necessary protobuf classes from the Bisq .proto files.

python-examples/README.md

@@ -1,4 +1,10 @@
 # Bisq API Python Examples
 
-The `run-setup.sh` script in this directory can be used to install Python dependencies and build the examples packages.
+This subproject contains Python3 classes demonstrating API gRPC method calls, and some sample bots.
+
+Each class in
+the [bisq.rpccalls](https://github.com/ghubstan/bisq-api-reference/tree/main/python-examples/bisq/rpccalls) package is
+named for the RPC method call being demonstrated.
+
+The `run-setup.sh` script in this directory can install Python3 dependencies and example packages into a local venv.
 

reference-doc-builder/README.md

@@ -0,0 +1,48 @@
+# Bisq API Reference Doc Builder
+
+The application script in this project consumes commented Bisq .proto
+files [pb.proto](https://github.com/bisq-network/bisq/blob/master/proto/src/main/proto/pb.proto),
+and [grpc.proto](https://github.com/bisq-network/bisq/blob/master/proto/src/main/proto/grpc.proto), and produces
+this [Slate](https://github.com/slatedocs/slate) compatible Markdown
+file:  [index.html.md](https://github.com/bisq-network/slate/blob/main/source/index.html.md)
+
+The Markdown file is then manually deployed to the bisq-network's fork of the
+[Slate repository](https://github.com/slatedocs/slate), where slate transforms it to a single html file describing Bisq
+gRPC API services: the [API Reference](https://bisq-network.github.io/slate).
+
+## Usage
+
+1. [Fork Slate](https://github.com/slatedocs/slate)
+
+
+2. Run `BisqApiDocMain`:
+
+<pre>
+BisqApiDocMain --protosIn=java-examples/src/main/proto \
+      --markdownOut=[path-to-slate-fork]/source \
+      --failOnMissingDocumentation=false
+</pre>
+
+3. Commit changes in your local slate/source file (`index.html.md`) _to your forked slate repo_.
+
+```asciidoc
+git commit -a -m "Update index.html.md"
+```
+
+4. Run slate's `deploy.sh` script
+
+
+5. You will see changes on in your forked slate's GitHub pages site after a few minutes. If your `index.html.md` file
+   was deployed to the bisq-network fork, the URL will be https://bisq-network.github.io/slate.
+
+## Credits
+
+Credit to [Juntao Han](https://github.com/mstao) for making his [markdown4j](https://github.com/mstao/markdown4j)
+API available for use in this project. His source code is included in this project, modified in ways to make generated
+markdown blocks compatible with Slate/GitHub style markdown.
+
+Lombok annotations are also replaced by the implementations they would generate if that had worked in my gradle
+development setup.
+
+
+