Installation¶
Normal HEPData users and data submitters should not need to install this package, since it is
automatically invoked when uploading a single text file with extension .oldhepdata
to the
hepdata.net submission system, or when requesting one of the
alternative output formats via the web interface.
To install this package locally, you first need to install YODA and
ROOT (including PyROOT). Check that you can
import yoda
and import ROOT
from Python. You might want to install into a dedicated virtual environment:
$ python3 -m venv hepdata-converter
$ source hepdata-converter/bin/activate
(hepdata-converter)$ pip install hepdata-converter
This will install the latest released version from PyPI.
Developers¶
Developers might want to instead install the project directly from GitHub in editable mode:
$ git clone https://github.com/HEPData/hepdata-converter
$ cd hepdata-converter
$ python3 -m venv venv
$ source venv/bin/activate
(venv)$ pip install -e '.[tests]'
Developers can then run the tests with the following command:
python -m unittest discover hepdata_converter/testsuite 'test_*'
The documentation can be built locally in the virtual environment using Sphinx:
(venv)$ pip install -e '.[docs]'
(venv)$ cd docs
(venv)$ make html
Then view the output by opening a web browser at _build/html/index.html
.
Developers should also check that they can successfully build other formats using make latexpdf
and make epub
.
All three formats will be built by Read the Docs for the main
branch on GitHub.
Docker¶
Alternatively, a Docker image is available (see
the hepdata-converter-docker repository)
containing the dependencies such as YODA and ROOT, but not the hepdata-converter
package itself.
$ docker pull hepdata/hepdata-converter
$ docker run --rm -it hepdata/hepdata-converter /bin/bash
The hepdata-converter
package can be installed inside the Docker container:
root@617be04cbab5:/# pip install hepdata-converter
root@617be04cbab5:/# hepdata-converter -h
root@617be04cbab5:/# python -c 'import hepdata_converter'
Note that the Docker container will be automatically removed when it exits (if running with the --rm
option). The
Python module or CLI can then be used as described in Usage. Input and output files can be moved
between the local filesystem and the running Docker container using the docker cp
command, for example,
$ docker cp sample.oldhepdata 617be04cbab5:/
root@617be04cbab5:/# hepdata-converter -i oldhepdata sample.oldhepdata SampleYAML
$ docker cp 617be04cbab5:/SampleYAML .
where the prompt $
indicates a terminal corresponding to the local filesystem and the prompt
root@617be04cbab5:/#
indicates another terminal corresponding to the running Docker container.
Alternatively, developers can install from GitHub and mount the current directory of the local filesystem when running the Docker container:
$ git clone https://github.com/HEPData/hepdata-converter
$ cd hepdata-converter
$ docker run -v $PWD:$PWD -w $PWD --rm -it hepdata/hepdata-converter /bin/bash
root@2c22e88402d2:/hepdata-converter# pip install -e '.[tests]'
root@2c22e88402d2:/hepdata-converter# hepdata-converter -h
root@2c22e88402d2:/hepdata-converter# python -c 'import hepdata_converter'
root@2c22e88402d2:/hepdata-converter# python -m unittest discover hepdata_converter/testsuite 'test_*'