diff --git a/doc/index.rst b/doc/index.rst index 72d73fa7b1e127514da00dc4f606e8db293bd7dc..4970a0e6262ddc5f04377a9c63e8ef90506482a7 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -108,6 +108,7 @@ Documentation contents :maxdepth: 2 howtos.rst + maintainers.rst Contribute diff --git a/doc/maintainers.rst b/doc/maintainers.rst new file mode 100644 index 0000000000000000000000000000000000000000..e2284e27a052d7d63c8c7a9e49f6f2eee477f294 --- /dev/null +++ b/doc/maintainers.rst @@ -0,0 +1,90 @@ +.. _maintainers: + +Maintainers +~~~~~~~~~~~ + +Creating a Toolbox environment in the proposal folder +----------------------------------------------------- + +A Toolbox environment can be created by running the following commands +in Maxwell: + +.. code::shell + + module exfel exfel_anaconda3 + scs-create-toolbox-env --proposal <PROPOSAL> + +where ``<PROPOSAL>`` is the desired proposal number. This will create a Python +environment and will download and install the Toolbox source code. It will +result to the creation of the following folders in the path +``<PROPOSAL_PATH>/usr/Software``. + +.. code-block:: + + <PROPOSAL_PATH>/usr/Software/ + ├─ checkouts/ + │ ├─ toolbox_<PROPOSAL>/ + │ │ ├─ <source code> + ├─ envs/ + │ ├─ toolbox_<PROPOSAL>/ + │ │ ├─ <Python files> + + +The ``checkouts`` folder contains the Toolbox source codes, correspondingly +labeled according to the environment identifier, which is the proposal number +by default. The downloaded code defaults to the **master** version at the +time when the environment is created. + +The ``envs`` folder contains the Python environment with the packages necessary +to run the Toolbox. It is also correspondingly labeled according to the +environment identifier, which is the proposal number by default. + +.. note:: + + One can find the proposal path by running ``find-proposal <PROPOSAL>``. + + +It is a good practice to tag the Toolbox version at a given milestone. +This version can be then supplied to the script as: + +.. code:: shell + + scs-create-toolbox-env --proposal <PROPOSAL> --version <VERSION> + + +It might also be helpful to supply an identifier to distinguish environments +from each other. This can be done by running: + +.. code:: shell + + scs-create-toolbox-env --proposal <PROPOSAL> --identifier <IDENTIFIER> + + +The environment would then be identified as ``toolbox_<IDENTIFIER>`` instead +of ``toolbox_<PROPOSAL>``. + + +Installing additional packages +------------------------------ + +In order to install additional packages in a Toolbox environment, one should +run the following commands: + +.. code::shell + + cd <PROPOSAL_PATH>/usr/Software/ + source envs/toolbox_<IDENTIFIER>/bin/activate + pip install ... + +There's no need to load the ``exfel`` module. + + +Updating the source codes +-------------------------- + +Should there be desired changes in the Toolbox codes, may it be bug fixes or +additional features during beamtime, one can freely modify the source codes in +the following path: ``<PROPOSAL_PATH>/usr/Software/checkouts/toolbox_<IDENTIFIER>``. +The contents of this folder should be a normal git repository. Any changes can +be easily done (e.g., editing a line of code, checking out a different +branch, etc.) and such changes are immediately reflected on the environment. diff --git a/setup.py b/setup.py index 202ee0dcae0c0b2c04225ec76a403eb02a8fe4fd..af8d03dd7c8170267dab5dc341ebd577263e6f6b 100644 --- a/setup.py +++ b/setup.py @@ -10,9 +10,10 @@ with open('VERSION') as f: basic_analysis_reqs = ['numpy', 'scipy',] # and is readily available in Karabo advanced_analysis_reqs = [ - 'pandas', 'imageio', 'xarray>=0.13.0', 'h5py', 'h5netcdf',] + 'pandas', 'imageio', 'xarray>=0.13.0', 'psutil', 'h5py', 'h5netcdf',] interactive_reqs = ['ipykernel', 'matplotlib', 'tqdm',] -maxwell_reqs = ['joblib', 'papermill', 'extra_data', 'euxfel_bunch_pattern>=0.6'] +maxwell_reqs = ['joblib', 'papermill', 'dask', + 'extra_data', 'euxfel_bunch_pattern>=0.6'] setup(name='toolbox_scs',