Merge pull request #237 from European-XFEL/version

Prepare for publishing

Dockerfile

@@ -19,6 +19,9 @@ RUN set -eux; \
     apt list --installed $(apt-mark showmanual) > /.apt-deps-build
 
 COPY pyproject.toml /src/pyproject.toml
+# We need to copy the README too because it's used in pyproject.toml when
+# building the package.
+COPY README.md /src/README.md
 
 # set up venv and python dependencies
 RUN set -eux; \

README.md

@@ -2,84 +2,6 @@
 
 [![Documentation Status](https://readthedocs.org/projects/damnit/badge/?version=latest)](https://damnit.readthedocs.io/en/latest/?badge=latest)
 
-## Installation
-```bash
-# Make an environment for DAMNIT
-git clone https://github.com/European-XFEL/DAMNIT.git
-cd DAMNIT
-conda create -n amore python
-
-conda activate amore
-pip install '.[gui,backend]'
-```
-
-## Usage
-Copy `context.py` to new folder (e.g. within proposal usr or scratch).
-This 'context dir' is also where it will save selected data. Edit `context.py`
-to define what data is interesting.
-
-To listen for new runs and extract data:
-```bash
-conda activate amore
-cd /path/to/proposal/scratch/amore  # Context directory
-amore-proto proposal 1234
-amore-proto listen .
-```
-
-The backend will write its logs to stdout, and also a file called `amore.log`
-in the same directory.
-
-To launch the GUI overview (e.g. on [max-exfl-display](https://max-exfl-display.desy.de:3389)):
-```bash
-conda activate amore
-amore-proto gui
-```
-
-You can open the context dir inside the GUI ('autoconfiguration'), or pass it
-at the command line.
-
-## Kafka
-The GUI is updated by Kafka messages sent by the backend. Currently we use
-XFEL's internal Kafka broker at `exflwgs06.desy.de:9091`, but this is only
-accessible inside the DESY network.
-
-DAMNIT can run offline, but if you want updates from the backend and you're
-running DAMNIT outside the network and not using a VPN, you'll first have to
-forward the broker port to your machine:
-```bash
-ssh -L 9091:exflwgs06.desy.de:9091 max-exfl.desy.de
-```
-
-And then add a line in your `/etc/hosts` file to resolve `exflwgs06.desy.de`
-to `localhost` (remember to remove it afterwards!):
-```
-127.0.0.1 exflwgs06.desy.de
-```
-
-And then DAMNIT should be able to use XFELs broker. If you want to use a specific
-broker you can set the `AMORE_BROKER` variable:
-```bash
-export AMORE_BROKER=localhost:9091
-```
-
-DAMNIT will then connect to the broker at that address.
-
-## Deployment on Maxwell
-DAMNIT is deployed in a module on Maxwell:
-```bash
-$ module load exfel amore
-```
-
-There was an idea in the beginning to potentially have multiple submodules for
-different instruments depending on how many people worked on features for
-instruments simultaneously, but so far we've just stuck with a single submodule
-for MID, `exfel amore/mid`, which is loaded by default with `exfel
-amore`. To update the module:
-```bash
-$ ssh [email protected]
-
-# Helper command to cd into the module directory and activate its environment
-$ amoremod mid
-$ git pull # Or whatever command is necessary to update the code
-$ pip install '.[gui]'
-```
+DAMNIT is a tool developed at the European XFEL to help users create an
+automated overview of their experiment. Check out the documentation for more
+information: https://damnit.rtfd.io

docs/data-storage.md → docs/internals.md

@@ -1,12 +1,67 @@
-# Data storage
+# Internals
 
-This page describes how DAMNIT saves the data it creates. This will probably not
-be of interest to you unless you're developing DAMNIT or writing tools that read
-data created by DAMNIT.
+This page describes some internal details of DAMNIT. It will probably not be of
+interest to you unless you're a developer.
 
----
+## Installation
 
-## Overview
+To install both the frontend and backend:
+```bash
+# Get the code
+git clone https://github.com/European-XFEL/DAMNIT.git
+cd DAMNIT
+
+# Make an environment for DAMNIT
+conda create -n damnit python
+
+conda activate damnit
+pip install '.[gui,backend]'
+```
+
+## Deployment on Maxwell
+DAMNIT is deployed in a stable and beta module on Maxwell:
+```bash
+$ module load exfel amore # The full path is actually amore/mid
+$ module load exfel amore/beta
+```
+
+To update a module:
+```bash
+$ ssh [email protected]
+
+# Helper command to cd into the module directory and activate its environment
+$ amoremod mid # This will activate the stable module, use `beta` for the beta module
+$ git pull # Or whatever command is necessary to update the code
+$ pip install '.[gui,backend]'
+```
+
+## Kafka
+The GUI is updated by Kafka messages sent by the backend. Currently we use
+XFEL's internal Kafka broker at `exflwgs06.desy.de:9091`, but this is only
+accessible inside the DESY network.
+
+DAMNIT can run offline, but if you want updates from the backend and you're
+running DAMNIT outside the network and not using a VPN, you'll first have to
+forward the broker port to your machine:
+```bash
+ssh -L 9091:exflwgs06.desy.de:9091 max-exfl.desy.de
+```
+
+And then add a line in your `/etc/hosts` file to resolve `exflwgs06.desy.de`
+to `localhost` (remember to remove it afterwards!):
+```
+127.0.0.1 exflwgs06.desy.de
+```
+
+And then DAMNIT should be able to use XFELs broker. If you want to use a specific
+broker you can set the `AMORE_BROKER` variable:
+```bash
+export AMORE_BROKER=localhost:9091
+```
+
+DAMNIT will then connect to the broker at that address.
+
+## Data storage
 
 There are two types of storage used, both in the `usr/Shared/amore` directory of
 a proposal by default:
@@ -24,7 +79,7 @@ a proposal by default:
 The DAMNIT data format details the exact structure of the data in the database
 and HDF5 files.
 
-## v1 (current)
+### v1 (current)
 
 In v1 there were a few changes to the way we store images and `xarray` types:
 
@@ -38,7 +93,7 @@ The most important change was to the database schema, which moved to a 'long
 narrow' format so that we don't need to change the schema whenever a new
 variable is added. It should also allow for versioning variables in the future.
 
-## v0
+### v0
 
 v0 refers to the first format, created before we started versioning at
 all. Here's an example v0 HDF5 file for a single run:

mkdocs.yml

@@ -55,8 +55,8 @@ nav:
   - index.md
   - gui.md
   - backend.md
-  - data-storage.md
   - api.md
+  - internals.md
   - contact.md
 
 plugins:

pyproject.toml

@@ -8,9 +8,12 @@ authors = [
     {name = "Thomas Kluyver", email = "[email protected]"},
     {name = "Luca Gelisio", email = "[email protected]"},
 ]
+description = "The Data And Metadata iNspection Interactive Thing"
 license = {file = "LICENSE"}
+requires-python = ">=3.9"
 classifiers = ["License :: OSI Approved :: BSD License"]
-dynamic = ["version", "description"]
+dynamic = ["version"]
+readme = "README.md"
 dependencies = [
     "h5netcdf",
     "h5py",