Merge branch 'add_metadata_templata_readme' into 'master'

Add metadata templata readme

See merge request !23

docs/README.md

+```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
+```
\ No newline at end of file

docs/README.rst

-README
-======
-
-.. literalinclude:: ../README.md
-   :lines: 9-
\ No newline at end of file

docs/index.rst

@@ -9,11 +9,11 @@ Welcome to eossr's documentation!
 .. toctree::
    :maxdepth: 2
    :glob:
-   :caption: Contents:
 
    README
    license
    docstring
+   metadata
    examples
    snippets
 

docs/metadata.md

+
+```{include} ../eossr/metadata/README.md
+:relative-docs: docs/
+:relative-images:
+```
\ No newline at end of file

eossr/metadata/README.md

+# ESCAPE metadata template
+
+Among the [OSSR guidelines and rules of participation](
+https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/contribute_ossr/) - agreed between the ESCAPE WP3 participants -, 
+we **strongly recommend** to include a metadata descriptive file into the entry to be uploaded to the ESCAPE repository.
+
+In the ESCAPE context, the use of the [CodeMeta schema](https://codemeta.github.io/) is strongly advised for uploads containing software. 
+However, we support and encourage the use of any other metadata standard. If this is the case, please contact us 
+(see just below). However, please note that the GitLab-Zenodo connection only supports - at the moment - codemeta metadata
+ descriptive files.  
+
+Any comments are more than welcome. Open an issue or contact us [via email](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
+
+## Quickstart - How to incorporate a CodeMeta metadata file into your project.
+
+ 1. Go to the [CodeMeta generator](https://codemeta.github.io/codemeta-generator/). Generate a `codemeta.json` file based on your project.
+    - Check - in the same web application - that the generated file is valid !  
+ 2. Copy the generated metadata into a `codemeta.json` file and include it in the **root directory** of your project.
+ 3. Please **pay attention to the `keywords` field**. Include **at least one** of the following keywords **per category**; 
+ besides all the keywords that you would like to attach to your project.   
+
+### Keywords list
+
+In your `codemeta.json` file **add, at least,** one keywords of the following **three** categories:
+
+Multiple keywords must be separated with a comma `,` and between double `"`;
+```json
+ {
+   ...
+ "keywords": ["CTA", "Astroparticle physics", "jupyter-notebook", ...],
+   ...  
+}
+```
+
+1. Project category:
+    - CTA
+    - LSST
+    - LOFAR
+    - SKA
+    - EGO-Virgo
+    - KM3NeT
+    - ELT
+    - EST
+    - HL-LHC
+    - FAIR
+    - CERN
+    - ESO
+    - JIVE
+    - IVOA
+    - EOSC
+    - ESO
+2. Domain category (single keywords):
+    - `Astronomy`
+    - `Astroparticle physics`
+    - `Particle physics`
+3. Notebooks category. At the moment only Jupyter notebooks are supported.
+    - Add `jupyter-notebook` as keyword if you project is based on or contains jupyter notebooks
+    - Do not add anything otherwise
+ 
+ 
+The reason to add the above keywords is just for classification and findability purposes in the OSSR (the
+ [ESCAPE2020 Zenodo community](https://zenodo.org/communities/escape2020) by other services such as the ESFRI Science Analysis Platform.
+ 
+## Create a Zenodo metadata file from the a CodeMeta schema file
+
+The zenodo repository does not accept codemeta metadata files yet. Meanwhile, the [eossr library](https://gitlab.in2p3.fr/escape2020/wp3/eossr) 
+provides a simple tool to create a native Zenodo metadata file (`.zenodo.json`) from a `codemeta.json` file. To do so;
+
+ 1. Include a `codemeta.json` file to the root directory of your project.
+ 2. Install this package;
+```bash
+ $ git clone https://gitlab.in2p3.fr/escape2020/wp3/eossr.git
+ $ cd eossr
+ $ pip install .
+```
+ 3. And then just run
+ ```bash
+ $ eossr-codemeta2zenodo --help
+ $ eossr-codemeta2zenodo --codemeta_file codemeta.json
+```
+
+Also, you can check and use the [**online codemeta2zenodo**](https://escape2020.pages.in2p3.fr/wp3/codemeta2zenodo/codemeta2zenodo.html)
+converter, based on the same library.
+
+In case of doubts or problems, please [contact us](mailto:vuillaume@lapp.in2p3.fr;garcia@lapp.in2p3.fr).
+
+
+**THIS STAGE IS RECOMMENDED, BUT NOT COMPULSORY FOR THE OSSR ONBOARDING.** 
+ - If you have linked your GitLab project with Zenodo using the autonomous procedure that [we propose](
+ https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_in_repository/), this stage will be done automatically. 
+ - If you are providing software via GitHub - and/or its [autonomous procedure](https://guides.github.com/activities/citable-code/) -, 
+ this stage is not mandatory (but still recommended). GitHub will take care of fetching the metadata from the project directly. 
+
+## Metadata schema templates
+
+Inside the `codemeta_utils` directory you will find two template files with **the all the properties (terms) of the corresponding metadata schema context** 
+ for both the CodeMeta metadata file and the Zenodo metadata file.
+ 
+Feel free to create and incorporate the metadata files starting from these templates. However, please note that  
+the final filenames **MUST** be either `codemeta.json` or `.zenodo.json` (note the `.` !). In case you do not fill or 
+write nothing on any dictionary key field, take it out of the file.
+
+In case of doubts please also check;
+  - The [CodeMeta properties/terms description](https://codemeta.github.io/terms/) or,
+  - the [`metadata representation`](https://developers.zenodo.org/#representation) allowed for the `.zenodo.json` metadata file.
+  
+  
+### Extending the CodeMeta Context schema
+
+In case you find that CodeMeta context does not describe deep enough your digital resource, you can extend the metadata 
+context and combine it with all the terms available at [https://schema.org](https://schema.org/docs/full.html).
+For this purpose, and following the [CodeMeta's developer guide](https://codemeta.github.io/developer-guide/);
+
+   1. Modify the `"@Context"` key of the `codemeta.json` as; 
+    
+    "@context": ["https://raw.githubusercontent.com/codemeta/codemeta/2.0-rc/codemeta.jsonld", "http://schema.org/"]
+     
+   2. Include the desired terms / properties following the `schema.org` context.
+   3. Contact us for a likely implementation into the OSSR environment ;-)
+
+
+-----------------
+-----------------
+
+
+### How to automatise the upload of a GitLab project to Zenodo via the GitLab-CI
+
+ - Add a `codemeta.js` file to your repository.
+ - Link your GitLab project and your Zenodo accounts.
+ - Add the following code snippet (Section 3. of the detailed tutorial) to the `.gitlab-ci.yml` file of your project and let the pipeline work !
+ - Check the [detailed tutorial](https://escape2020.pages.in2p3.fr/wp3/ossr-pages/page/contribute/publish_tutorial/) for more details.