Added codox documentation generation; updated README.

README.md

@@ -16,21 +16,97 @@ A Clojure library designed to explore donations data for people in Gaza whose ac
 
 This is a very experimental, unfinished and unpolished library designed for use with leiningen. To use, clone this repository, connect to the directory into which you cloned it, and type `lein repl`.
 
-At present two useful functions are implemented:
+At present several useful functions are implemented:
 
-### `(total-donations-by-weeks start-date end-date)`
+### accounts-with-donations-by-date-range
 
-Return a list of pairs [java.time.LocalDate date, float amount] representing
+```
-the total of donations made between `start-date` and `end-date`. Arguments may
+(accounts-with-donations-by-date-range start-date end-date)
-be supplied as `java.time.LocalDate` objects, or as strings in the format
+```
-`yyyy-mm-dd`. If `end-date` is not supplied, data for a single week will be
-returned.
 
-### `(chart-total-donations-by-weeks start-date end-date)`
+Return a list of maps, each representing one account from the `gaza.onl` database, with a key `:donations`, whose value is a float representing the total donations received by that account between the dates `start-date` (exclusive) and `end-date` (inclusive). Date arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`.
 
-Create and return an XY chart of data on total donations made between
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L98)
-`start-date` and `end-date`. Arguments may be supplied as
+
-`java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`.
+### chart-accounts-with-donations-by-months-in-range
+
+```
+(chart-accounts-with-donations-by-months-in-range start-date end-date)
+```
+
+Return a chart with one line for each calendar month covering from `start-date` (inclusive) to `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`, showing donations as for `chart-donations-by-accounts-in-date-range`, q.v.
+
+TODO: There are currently two problems with this at present: chart  legends are not displayed in sequential order; and there appears to be  occasional spurious data (but I don’t know why).
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L138)
+
+### chart-donations-as-percentage-in-date-range
+
+```
+(chart-donations-as-percentage-in-date-range start-date end-date)
+```
+
+Return a chart of donations received by individual accounts between `start-date` (exclusive) and `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. Accounts are identified in the chart only by rank order.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L125)
+
+### chart-donations-by-accounts-in-date-range
+
+```
+(chart-donations-by-accounts-in-date-range start-date end-date)
+```
+
+Return a chart of donations received by individual accounts between `start-date` (exclusive) and `end-date` (inclusive). Arguments should be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. Accounts are identified in the chart only by rank order.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L115)
+
+### chart-donations-by-weeks
+
+```
+(chart-donations-by-weeks start-date end-date key)
+```
+
+Create and return an XY chart of data on field represented by `key` of donations made between  `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L58)
+
+### chart-number-donations-by-weeks
+
+```
+(chart-number-donations-by-weeks start-date end-date)
+```
+
+Create and return an XY chart of data on number of donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L75)
+
+### chart-total-donations-by-weeks
+
+```
+(chart-total-donations-by-weeks start-date end-date)
+```
+
+Create and return an XY chart of data on total donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L68)
+
+### enhance-account-with-donations
+
+```
+(enhance-account-with-donations account-map sd ed)
+```
+
+Take this `account_map`, which must at least have a valid value for the key `:campaign_url` and return a similar map including the key `:donations`, whose value is a float representing the total donations received by that campaign URL between the dates `sd` (exclusive) and `ed` (inclusive). Date arguments should be supplied as `java.time.LocalDate` objects.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L82)
+
+### total-donations-by-weeks
+
+`(total-donations-by-weeks start-date)``(total-donations-by-weeks start-date end-date)`
+
+Return a list of pairs [java.time.LocalDate date, float amount](file:///home/simon/workspace/gaza-stats/docs/codox/java.time.LocalDate date, float amount) representing the total of donations made between `start-date` and `end-date`. Arguments may be supplied as `java.time.LocalDate` objects, or as strings in the format `yyyy-mm-dd`. If `end-date` is not supplied, data for a single week will be returned.
+
+[view source](https://github.com/simon-brooke/gaza-stats/blob/main/src/gaza_stats/core.clj#L18)
 
 ### Viewing charts
 

project.clj

@@ -1,4 +1,12 @@
 (defproject gaza-stats "0.1.0-SNAPSHOT"
+  :codox {:froboz.cloverage {:output "docs/cloverage"
+                               :codecov? true
+                               :html? true
+                               :debug? true}
+            :metadata {:doc "**TODO**: write docs"
+                       :doc/format :markdown}
+            :output-path "docs/codox"
+            :source-uri "https://github.com/simon-brooke/gaza-stats/blob/main/{filepath}#L{line}"}
   :dependencies [[org.clojure/clojure "1.12.6"]
                  [com.hypirion/clj-xchart "0.2.0"]
                  [korma "0.4.3"]
@@ -6,8 +14,8 @@
                  [org.xerial/sqlite-jdbc "3.7.15-M1"]]
   :description "FIXME: write description"
   ;; :jvm-opts ["-Xmx4g"]
-  :license {:name "GNU General Public License,version 2.0 or (at your option) an
+  :license {:name "GNU General Public License,version 2.0 or (at your option) any later version"
-y later version"
             :url "https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html"}
+  :plugins [[lein-codox "0.10.8"]]
   :repl-options {:init-ns gaza-stats.core}
   :url "http://example.com/FIXME")

src/gaza_stats/core.clj

@@ -136,6 +136,15 @@
                [(range (count data)) percentages]})))
 
 (defn chart-accounts-with-donations-by-months-in-range
+  "Return a chart with one line for each calendar month covering from
+  `start-date` (inclusive) to `end-date` (inclusive). Arguments should be
+  supplied as `java.time.LocalDate` objects, or as strings in the format
+  `yyyy-mm-dd`, showing donations as for
+  `chart-donations-by-accounts-in-date-range`, q.v.
+
+  TODO: There are currently two problems with this at present: chart legends
+  are not displayed in sequential order; and there appears to be occasional
+  spurious data (but I don't know why)."
   [start-date end-date]
   (let [sd (cond (date? start-date) start-date
                  (string? start-date) (ld/parse start-date)