From 45f6704f207a9d43bff1478a1e5506a9d59739ef Mon Sep 17 00:00:00 2001 From: ghubstan <36207203+ghubstan@users.noreply.github.com> Date: Mon, 28 Mar 2022 09:30:04 -0300 Subject: [PATCH] Improve documentation in top-level and subproject READMEs --- README.md | 65 ++++++++++++--------------------- cli-examples/README.md | 7 ++++ java-examples/README.md | 11 ++++++ python-examples/README.md | 8 +++- reference-doc-builder/README.md | 48 ++++++++++++++++++++++++ 5 files changed, 96 insertions(+), 43 deletions(-) create mode 100644 cli-examples/README.md create mode 100644 java-examples/README.md create mode 100644 reference-doc-builder/README.md diff --git a/README.md b/README.md index c089264..4288b24 100644 --- a/README.md +++ b/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 -`index.html.md` -- a [Slate](https://github.com/slatedocs/slate) compatible Markdown file. +This project's main purpose is to generate the Markdown text for +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 -[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=/proto - \ --markdownOut=/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,
- 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. +It contains four subprojects: +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. diff --git a/cli-examples/README.md b/cli-examples/README.md new file mode 100644 index 0000000..16c4ad2 --- /dev/null +++ b/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. + + diff --git a/java-examples/README.md b/java-examples/README.md new file mode 100644 index 0000000..4e23ec1 --- /dev/null +++ b/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. diff --git a/python-examples/README.md b/python-examples/README.md index 0c9be79..9d46eb5 100644 --- a/python-examples/README.md +++ b/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. diff --git a/reference-doc-builder/README.md b/reference-doc-builder/README.md new file mode 100644 index 0000000..102e685 --- /dev/null +++ b/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`: + +
+BisqApiDocMain --protosIn=java-examples/src/main/proto \
+      --markdownOut=[path-to-slate-fork]/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. 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. + + +