diff --git a/math/README.md b/math/README.md index 529bd195e..7951bf88f 100644 --- a/math/README.md +++ b/math/README.md @@ -26,7 +26,7 @@ This message may get quickly swamped out by a stream of other logging messages r Regardless, at this point, the system is running and can be connected to. Most editor plugins will connect somewhat automatically if you try to evaluate code or display documentation, but you can refer to the documentation for your editor of choice if this is not the case. -To get a sense for how various parts of these system can be used, take a look at the comment block at the [bottom of `dev/user.clj`](https://github.com/compdemocracy/polis/blob/dev/math/dev/user.clj#L328). +To get a sense for how various parts of these system can be used, take a look at the comment block at the [bottom of `dev/user.clj`](dev/user.clj#L328). If you're not familiar with Clojure and want a fun crash course, I highly recommend [Clojure for the Brave and True](https://www.braveclojure.com/), a delightful introduction to the language. @@ -34,8 +34,7 @@ If you're not familiar with Clojure and want a fun crash course, I highly recomm If you're not using the docker compose infrastructure, you can run `clj -M:dev` to get nREPL going, but this will not start math worker's processing queue (or obviously any other parts of the system). This may be preferable if you don't need the whole system running for whatever task you're working on. -You can always manually start the polling system by manually running `(runner/run!)`, as described below, as long as you have the `DATABASE_URL` environment variable pointing to a database (see `doc/configuration.md`) - +You can always manually start the polling system by manually running `(runner/run!)`, as described below, as long as you have the `DATABASE_URL` environment variable pointing to a database (see [`doc/configuration.md`](doc/configuration.md)) ## Starting and stopping the system This application uses Stuart Sierra's Component library for REPL-reloadability. @@ -66,8 +65,8 @@ If you are exporting data, you will need to run `docker compose` here with the s You can run tests by executing `clojure -M:test`. -Since Clojure is slow to start though, you may find it easier to run the `test-runner/-main` function (located at `tests/test_runner.clj`) from within your nREPL process. -There is an example of this in the `dev/user.clj` file mentioned above. +Since Clojure is slow to start though, you may find it easier to run the `test-runner/-main` function (located at [`test/test_runner.clj`](test/test_runner.clj)) from within your nREPL process. +There is an example of this in the [`dev/user.clj`](dev/user.clj) file mentioned above. There are rough units tests for most of the basic math things, and one or two higher level integration tests (presently broken). We're looking forward to setting up `clojure.spec` and some generative testing for more thorough coverage if this is something that excites you! @@ -79,11 +78,11 @@ The reason for this particular design is that when a conversation is very active Meanwhile, the time it takes to run an update increases. We need to have a way of queueing up vote and moderation data updates, so that they're ready to be processed once the last conversation update has completed. -You can see the conversation manager implementation at `src/polismath/conv_man.clj`. +You can see the conversation manager implementation at [`src/polismath/conv_man.clj`](src/polismath/conv_man.clj). ## Production setup -The `docker-compose.yml` file in the root of this directory, while not yet production ready, and still containing some development time artifacts, is provided as a basis for production deployment. +The [`docker-compose.yml`](../docker-compose.yml) file in the root of this directory, while not yet production ready, and still containing some development time artifacts, is provided as a basis for production deployment. Outstanding issues which need to be resolved before it would be ready include ensuring only necessary ports are exposed, etc. The individual `Dockerfile`s that make up this infrastructure can currently be used by themselves, separate from `docker compose`, for deployment. @@ -92,7 +91,7 @@ Nonetheless, if you wish to run this part of the system directly on a machine (o * [install Clojure](https://clojure.org/guides/getting_started). * Setup the postgresql client (`sudo apt-get install postgresql postgresql-client` on ubuntu). -If you go this route you will want to take a look at the [configuration docs](./doc/configuration). +If you go this route you will want to take a look at the (see [`doc/configuration.md`](doc/configuration.md)). ## Licensing