Feedback from JOSS review (#139)

.github/workflows/docs.yml

@@ -1,6 +1,6 @@
 name: Documentation build
 
-# on: push
+  # on: push
 on:
   release:
     types: [published]
@@ -22,19 +22,30 @@ jobs:
       uses: actions/setup-python@v2
       with:
         python-version: 3.7
+    - name: Install latex
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y texmaker latexmk
     - name: Add conda to system path
       run: |
         # $CONDA is an environment variable pointing to the root of the miniconda directory
         echo $CONDA/bin >> $GITHUB_PATH
     - name: Install dependencies
       run: |
-        conda env update --file salmon.yml --name base
+        conda env update --file salmon.lock.yml --name base
     - name: Install Salmon
-      run: pip install -e .
+      run: |
+        pip install -e ".[dev,server]"
     - name: Build docs
       run: |
         cd docs
         make html
+    - name: Build backup docs
+      run: |
+        cd docs
+        sudo apt-get install -y texmaker latexmk
+        make latexpdf
+        mv build/latex/salmon.pdf build/html/salmon.pdf
     - name: Upload docs to gh-pages branch
       uses: peaceiris/actions-gh-pages@v3
       with:

.github/workflows/test.yml

@@ -1,4 +1,4 @@
-name: Tests (complete w/ conda)
+name: Tests (install w/ pinned conda)
 
 on:
   push:
@@ -42,9 +42,11 @@ jobs:
           sudo chown -R -H -L $USER:$USER salmon docs tests
     - name: Install dependencies
       run: |
-        conda env update --file salmon.yml --name base
+        conda env update --file salmon.lock.yml --name base
     - name: Install Salmon
-      run: pip install -e .
+      run: |
+        pip install .
+        pip install pytest
     - name: Run tests in salmon/salmon/
       run: sudo /usr/share/miniconda/bin/pytest salmon/
     - uses: docker/setup-buildx-action@v1

.github/workflows/test_conda.yml

@@ -0,0 +1,64 @@
+name: Tests (install w/ conda)
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+
+  build:
+
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Python 3.7
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+    - name: Add conda to system path
+      run: |
+        # $CONDA is an environment variable pointing to the root of the miniconda directory
+        echo $CONDA/bin >> $GITHUB_PATH
+    - name: Debug info
+      run: |
+          echo "Running pwd..."
+          pwd
+          echo "\nRunning echo $USER..."
+          echo $USER
+          echo "\nRunning chown..."
+          sudo chown -R -H -L $USER:$USER  /home/runner/work/salmon/
+          chown -R -H -L $USER:$USER /home/runner/work/salmon/
+          echo "\nRunning chmod..."
+          sudo chmod -R 777 /home/runner/work/salmon/
+          echo "\nRunning `ls`..."
+          ls
+    - name: Prepare for docker build...
+      run: |
+          chmod +x launch.sh
+          # chown -R -H -L $USER:$USER .
+          sudo chown -R -H -L $USER:$USER .
+          sudo chown -R -H -L $USER:$USER salmon docs tests
+    - name: Install dependencies
+      run: |
+        conda env update --file salmon.yml --name base
+    - name: Install Salmon
+      run: pip install -e .
+    - name: Run tests in salmon/salmon/
+      run: sudo /usr/share/miniconda/bin/pytest salmon/
+    - uses: docker/setup-buildx-action@v1
+      with:
+        driver: docker
+    - name: Build Salmon server w/ Docker
+      env:
+        SALMON_NO_AUTH: 1
+      run: |
+          sudo --preserve-env=SALMON_NO_AUTH docker-compose up &
+          until curl 127.0.0.1:8421 > /dev/null 2>&1; do :; done  # wait for container to start
+          sudo docker ps
+    - name: Run all tests
+      run: |
+          # sudo docker-compose logs -f &  # if debugging; shows logs
+          # sudo /usr/share/miniconda/bin/pytest -s
+          sudo /usr/share/miniconda/bin/pytest

.github/workflows/test_offline.yml

@@ -1,4 +1,4 @@
-name: Test (offline)
+name: Offline tests (install w/ pip)
 
 on:
   push:
@@ -45,7 +45,9 @@ jobs:
           sudo chown -R -H -L $USER:$USER .
           sudo chown -R -H -L $USER:$USER salmon docs tests
     - name: Install Salmon
-      run: pip install .
+      run:
+        pip install .
+        pip install pytest
     - name: change directories
       run: cd /
     - name: Debug info (salmon.__file__)
@@ -54,5 +56,3 @@ jobs:
           python -c "import salmon; print(salmon.__file__)"
     - name: Run offline tests
       run: sudo /usr/share/miniconda/bin/pytest /home/runner/work/salmon/salmon/tests/test_offline.py
-    - name: Run tests in salmon/salmon/
-      run: sudo /usr/share/miniconda/bin/pytest /home/runner/work/salmon/salmon/salmon

.github/workflows/test_pip.yml

@@ -1,4 +1,4 @@
-name: Tests (complete w/ pip)
+name: Tests (install w/ pip)
 
 on:
   push:
@@ -42,7 +42,7 @@ jobs:
           sudo chown -R -H -L $USER:$USER salmon docs tests
     - name: Install dependencies
       run: |
-        pip install .
+        pip install ".[server,dev]"
     - name: Run tests in salmon/salmon/
       run: sudo /usr/share/miniconda/bin/pytest salmon/
     - uses: docker/setup-buildx-action@v1

Dockerfile

@@ -4,18 +4,18 @@ RUN apt-get update
 RUN apt-get install -y gcc cmake g++
 RUN conda -V
 
-COPY salmon.yml /salmon/salmon.yml
-RUN conda env update -n base --file /salmon/salmon.yml --prune
+COPY salmon.lock.yml /salmon/salmon.lock.yml
+RUN conda env create -f /salmon/salmon.lock.yml
 
 VOLUME /salmon
 VOLUME /data
 COPY *.py *.cfg *.yml *.txt *.sh /salmon/
 COPY ./salmon/ /salmon/salmon/
 RUN ls /salmon
-RUN pip install -e /salmon
+RUN conda run -n salmon pip install -e /salmon[server]
 
 RUN chmod +x /salmon/launch.sh
 RUN chmod +rw /salmon
 # ENTRYPOINT bash launch.sh
 WORKDIR /salmon
-CMD ["bash", "launch.sh"]
+CMD ["conda", "run", "--no-capture-output", "-n", "salmon", "/bin/bash", "launch.sh"]

LICENSE.txt

@@ -1,21 +1,29 @@
-MIT License
+BSD 3-Clause License
 
-Copyright (c) 2020-2021 Scott Sievert and Salmon contributors.
+Copyright (c) 2019, Scott Sievert and contributors
+All rights reserved.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -2,6 +2,9 @@
 <a href="https://github.com/stsievert/salmon/actions/workflows/test.yml">
  <img src="https://github.com/stsievert/salmon/actions/workflows/test.yml/badge.svg?branch=master" />
 </a>
+<a href="https://github.com/stsievert/salmon/actions/workflows/test_pip.yml">
+ <img src="https://github.com/stsievert/salmon/actions/workflows/test_pip.yml/badge.svg?branch=master" />
+</a>
 <a href="https://github.com/stsievert/salmon/actions/workflows/test_offline.yml">
   <img src="https://github.com/stsievert/salmon/actions/workflows/test_offline.yml/badge.svg?branch=master" />
 </a>
@@ -13,14 +16,30 @@ Salmon is a tool for efficiently generating ordinal embeddings. It relies on
 "active" machine learning algorithms to choose the most informative queries for
 humans to answer.
 
-See the documentation for more detail: https://docs.stsievert.com/salmon/
+### Documentation
+
+This documentation is available at these locations:
+
+* **Primary source**: https://docs.stsievert.com/salmon/
+* Secondary source: as [a raw PDF][pdf] (and as a [slower loading PDF][blobpdf]).
+* Secondary source: as [zipped HTML directory][ziphtml], which requires unzipping the directory
+  then opening up `index.html`.
+
+[pdf]:https://github.com/stsievert/salmon/raw/gh-pages/salmon.pdf
+[blobpdf]:https://github.com/stsievert/salmon/blob/gh-pages/salmon.pdf
+[ziphtml]:https://github.com/stsievert/salmon/archive/refs/heads/gh-pages.zip
+
+Please [file an issue][issue] if you can not access the documentation.
+
+[issue]:https://github.com/stsievert/salmon/issues/new
 
 ### Running Salmon offline
 Visit the documentation at https://docs.stsievert.com/salmon/offline.html.
 Briefly, this should work:
 
 ``` shell
-$ conda env create -f salmon.yml
+$ cd path/to/salmon
+$ conda env create -f salmon.lock.yml
 $ conda activate salmon
 (salmon) $ pip install -e .
 ```

docker-compose.yml

@@ -12,6 +12,7 @@ services:
       - "8421:8421"
       - "8400:8400"
       - "8787:8787"
+    depends_on: [redis]
     expose:
       - 8421
       - 8400
@@ -30,31 +31,29 @@ services:
     volumes:
       - "./salmon/_out:/data:rw"
     command: /bin/sh -c "chmod -v 777 /data && redis-server --loadmodule /usr/lib/redis/modules/rejson.so"
-    # redis-server command from https://hub.docker.com/r/redislabs/rejson/dockerfile
-    #
-    # https://github.com/docker/compose/issues/3270
-    # also https://github.com/boot2docker/boot2docker/issues/1083#issuecomment-151380687
-
-    # redismonitor:
-    #   user: root
-    #   build: docker/redismonitor
-    #   ports:
-    #     - "7381:7389"
-    #   volumes:
-    #     - "./out:/logs:rw"
-    #   logging:
-    #     driver: none
 
   prom:
     image: prom/prometheus
+    depends_on: [redis]
     expose:
       - 9090
     volumes:
       - ./docker/prom:/etc/prometheus
-        #  granfna:
-        #    image: grafana/grafana
-        #    ports:
-        #      - "3000:3000"
+
+  # redismonitor:
+  #   user: root
+  #   build: docker/redismonitor
+  #   ports:
+  #     - "7381:7389"
+  #   volumes:
+  #     - "./out:/logs:rw"
+  #   logging:
+  #     driver: none
+
+# redis-server command from https://hub.docker.com/r/redislabs/rejson/dockerfile
+#
+# https://github.com/docker/compose/issues/3270
+# also https://github.com/boot2docker/boot2docker/issues/1083#issuecomment-151380687
 
 # To get bash on one of these machines:
 # docker exec -it <containerIdOrName> bash

docs/requirements.txt

@@ -0,0 +1 @@
+numpydoc

docs/source/adaptive.rst

@@ -1,5 +1,5 @@
-Adaptive algorithms
-===================
+Adaptive algorithm primer
+=========================
 
 The API the must conform to below:
 

docs/source/benchmarks/active.rst

@@ -116,15 +116,15 @@ accuracy. To start, let's assume that there's no clear relationship between
 items. Then, this visualization is most appropriate for the embeddings of
 particular accuracies:
 
-.. image:: imgs/embeddings-n=30-colorless.svg
+.. image:: imgs/embeddings-n=30-colorless.png
    :width: 90%
    :align: center
 
 These embeddings are remarkably simple, and have a clear and known
 relationship. Because of that, let's show the embeddings with colors from now
 on:
 
-.. image:: imgs/embeddings-n=30.svg
+.. image:: imgs/embeddings-n=30.png
    :width: 95%
    :align: center
 
@@ -162,7 +162,7 @@ Embedding quality
 Here's the underlying embeddings for :math:`n = 180` for various accuracy
 levels on *simulated* human responses:
 
-.. image:: imgs/embeddings-n=180.svg
+.. image:: imgs/embeddings-n=180.png
    :width: 100%
    :align: center
 

docs/source/conf.py

@@ -24,9 +24,9 @@
 author = "Scott Sievert"
 
 # The full version, including alpha/beta/rc tags
-from salmon import __version__
-
-release = __version__.replace(".dirty", "")
+# from salmon import __version__
+#
+# release = __version__.replace(".dirty", "")
 
 html_context = {
     "display_github": True,  # Integrate GitHub