From 0c02e16fbebd7f00d0d3614cc20995a51eb18fe9 Mon Sep 17 00:00:00 2001
From: temok-mx <temok.mx@gmail.com>
Date: Thu, 10 Sep 2020 17:23:12 +0200
Subject: [PATCH] Updated README.md; added metadata.yml; the lead branch is now
 master, inactive branches became tags

---
 README.md    | 85 ++++++++++++++++++++++++++++++++++++++++++++--------
 metadata.yml |  8 +++++
 2 files changed, 80 insertions(+), 13 deletions(-)
 create mode 100644 metadata.yml

diff --git a/README.md b/README.md
index 8fd10f6..4146bde 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,78 @@
-# mpesparser
-@author = R. Patrick Xian (xian@fhi-berlin.mpg.de)
+This is a NOMAD parser for [MPES](https://mpes-kit.github.io/mpes). It will read MPES input and
+output files and provide all information in NOMAD's unified Metainfo based Archive format.
 
-## About
+## Preparing code input and output file for uploading to NOMAD
 
-Multidimensional photoemission spectroscopy (MPES) experimental data parser for NOMAD-FAIR database.
+NOMAD accepts `.zip` and `.tar.gz` archives as uploads. Each upload can contain arbitrary
+files and directories. NOMAD will automatically try to choose the right parser for you files.
+For each parser (i.e. for each supported code) there is one type of file that the respective
+parser can recognize. We call these files `mainfiles` as they typically are the main
+output file a code. For each `mainfile` that NOMAD discovers it will create an entry
+in the database that users can search, view, and download. NOMAD will associate all files
+in the same directory as files that also belong to that entry. Parsers
+might also read information from these auxillary files. This way you can add more files
+to an entry, even if the respective parser/code might not directly support it.
 
-## Description of files
-The set of important files for the parser are explained in the following,
-- [mpesparser](mpesparser): Main folder of the parser.
-- [mpesparser/__init__.py](mpesparser/__init__.py): Parser module initialization code.
-- [mpesparser/__main__.py](mpesparser/__main__.py): Parser module run file.
-- [mpesparser/mpes.nomadmetainfo.json](mpesparser/mpes.nomadmetainfo.json): MPES metadata definitions.
+For mpes please provide at least the files from this table if applicable to your
+calculations (remember that you can provide more files if you want):
 
-To run the parser:
+
+
+To create an upload with all calculations in a directory structure:
+
+```
+zip -r <upload-file>.zip <directory>/*
+```
+
+Go to the [NOMAD upload page](https://nomad-lab.eu/prod/rae/gui/uploads) to upload files
+or find instructions about how to upload files from the command line.
+
+## Using the parser
+
+You can use NOMAD's parsers and normalizers locally on your computer. You need to install
+NOMAD's pypi package:
+
+```
+pip install nomad-lab
+```
+
+To parse code input/output from the command line, you can use NOMAD's command line
+interface (CLI) and print the processing results output to stdout:
+
+```
+nomad parse --show-archive <path-to-file>
 ```
-cd nomad/dependencies/parsers/parser-mpes
-python -m parser-mpes tests/mpes.metadata_redacted.json
+
+To parse a file in Python, you can program something like this:
+```python
+import sys
+from nomad.cli.parse import parse, normalize_all
+
+# match and run the parser
+backend = parse(sys.argv[1])
+# run all normalizers
+normalize_all(backend)
+
+# get the 'main section' section_run as a metainfo object
+section_run = backend.resource.contents[0].section_run[0]
+
+# get the same data as JSON serializable Python dict
+python_dict = section_run.m_to_dict()
+```
+
+## Developing the parser
+
+Also install NOMAD's pypi package:
+
+```
+pip install nomad-lab
 ```
+
+Clone the parser project and install it in development mode:
+
+```
+git clone https://gitlab.mpcdf.mpg.de/nomad-lab/parser-mpes parser-mpes
+pip install -e parser-mpes
+```
+
+Running the parser now, will use the parser's Python code from the clone project.
diff --git a/metadata.yml b/metadata.yml
new file mode 100644
index 0000000..3bdf208
--- /dev/null
+++ b/metadata.yml
@@ -0,0 +1,8 @@
+code-label: MPES
+code-label-style: All in capitals
+code-url: https://mpes-kit.github.io/mpes
+parser-dir-name: dependencies/parsers/mpes/
+parser-git-url: https://gitlab.mpcdf.mpg.de/nomad-lab/parser-mpes
+parser-specific: |
+  MPES (Multidimensional photoemission spectroscopy) is a parser for experimental data.
+table-of-files: ''
-- 
GitLab