Add a little documentation

README.md

@@ -2,5 +2,43 @@
 
 This repo contains Haskell packages for working with CQG's APIs:
 
-- [CQG CMS API](https://partners.cqg.com/api-resources/cms-api)
+- [CQG CMS API](https://partners.cqg.com/api-resources/cms-api) [`./cqg-cms-api-proto`](./cqg-cms-api-proto/)
 - [CQG Web API](https://partners.cqg.com/api-resources/web-api) (_not yet implemented_)
+
+## Viewing Documentation for Generated Haskell Modules
+
+In order to figure out how to use the generated Haskell modules, you'll find
+the following pieces of documentation helpful:
+
+-   The [proto-lens tutorial](http://google.github.io/proto-lens/tutorial.html).
+    This is somewhat brief, but touches on most aspects of using `proto-lens`.
+
+-   The Haddocks of the generated Haskell modules.  You can generate the
+    Haddocks with the command:
+
+    ```console
+    $ stack haddock
+    ```
+
+-   The raw `.proto` files themselves, for instance in
+    [`./cqg-cms-api-proto/proto`].  The `.proto` files also contain helpful
+    comments that don't get generated in the Haddocks.
+
+    Once you understand how the translation works between the `.proto` files
+    and the Haskell modules, it is often easier to just read the `.proto` files
+    instead of the Haddocks.
+
+-   Any example code from CQG for working with their APIs.  For instance, there is an
+    [example Protobuf-based Python project](https://partners.cqg.com/api-resources/cms-api/documentation)
+    for working with the CQG CMS API.  Translating the Python examples to
+    Haskell is at least _somewhat_ straightforward.
+
+## Regenerating Haskell Modules
+
+You can redownload the protobuf files for CQG's APIs, and then regenerate the
+Haskell modules with the following command.  This is a `nix-shell` script, so
+make sure you have Nix installed before running this command:
+
+```console
+$ ./generate.sh
+```

cqg-cms-api-proto/README.md

@@ -1 +1,3 @@
 # cqg-cms-api-proto
+
+This package contains Haskell modules generated from the protobuf files for CQG's [CMS API](https://partners.cqg.com/api-resources/cms-api/documentation).

cqg-cms-api-proto/cqg-cms-api-proto.cabal

@@ -17,7 +17,6 @@ license-file:   LICENSE
 build-type:     Simple
 extra-source-files:
     README.md
-    CHANGELOG.md
     proto/CMS/api_limit_1.proto
     proto/CMS/cmsapi_1.proto
     proto/CMS/common_1.proto

cqg-cms-api-proto/package.yaml

@@ -7,7 +7,6 @@ copyright:           "2024 Bitnomial, Inc"
 
 extra-source-files:
   - README.md
-  - CHANGELOG.md
   - proto/**/*.proto
 
 synopsis:            "Haskell modules generated from Protobuf definitions of the CQG CMS API"

generate.sh

@@ -0,0 +1,29 @@
+#! /usr/bin/env nix-shell
+#! nix-shell -i bash
+# nixos-24.05 as of 2024-06-01
+#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/805a384895c696f802a9bf5bf4720f37385df547.tar.gz
+#! nix-shell -p curl
+#! nix-shell -p unzip
+#! nix-shell -p protobuf
+#! nix-shell -p haskellPackages.proto-lens-protoc
+#
+# This script will download and regenerate the CQG API Protobuf files.
+
+# Make sure shellcheck understands that this is a Bash script:
+# shellcheck shell=bash
+
+set -eumo pipefail
+
+shopt -s globstar
+
+# Download the protobuf files
+
+rm -rf cqg-cms-api-proto/proto/*
+curl 'https://partners.cqg.com/cms/protocol/production/CMS.zip' > cqg-cms-api-proto/proto/CMS.zip
+unzip cqg-cms-api-proto/proto/CMS.zip -d cqg-cms-api-proto/proto/
+rm cqg-cms-api-proto/proto/CMS.zip
+
+# Generate the Haskell modules from the protobuf files
+
+rm -rf cqg-cms-api-proto/src/*
+protoc --plugin=protoc-gen-haskell="$(which proto-lens-protoc)" --haskell_out=cqg-cms-api-proto/src/ --proto_path=cqg-cms-api-proto/proto cqg-cms-api-proto/proto/**/*.proto