Metadata-Version: 2.1
Name: nfdi4earth-kh-schema
Version: 0.4.12b11
Summary: Python package for working with data in conformance with the NFDI4Earth Knowledge Hub schema
Author-email: Jonas Grieb <jonas.grieb@senckenberg.de>, Ralf Klammer <ralf.klammer@tu-dresden.de>
Maintainer-email: Jonas Grieb <jonas.grieb@senckenberg.de>, Ralf Klammer <ralf.klammer@tu-dresden.de>
License: Apache-2.0
Project-URL: Homepage, https://git.rwth-aachen.de/jgrieb/nfdi4earth-kh-schema
Project-URL: Documentation, https://nfdi4earth.pages.rwth-aachen.de/knowledgehub/nfdi4earth-kh-schema/
Project-URL: Source, https://git.rwth-aachen.de/jgrieb/nfdi4earth-kh-schema
Project-URL: Tracker, https://git.rwth-aachen.de/jgrieb/nfdi4earth-kh-schema/issues/
Keywords: linkml
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSES/Apache-2.0.txt
License-File: LICENSES/CC-BY-4.0.txt
License-File: LICENSES/CC0-1.0.txt
Requires-Dist: linkml==1.6.11
Requires-Dist: linkml-runtime==1.6.3
Requires-Dist: rdflib==6.3.2
Provides-Extra: docs
Requires-Dist: mkdocs; extra == "docs"
Requires-Dist: mkdocs-mermaid2-plugin; extra == "docs"
Requires-Dist: mkdocs-material; extra == "docs"
Requires-Dist: versioneer; extra == "docs"
Provides-Extra: dev
Requires-Dist: nfdi4earth-kh-schema[docs]; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"

<!--
SPDX-FileCopyrightText: 2023 Senckenberg Society for Nature Research, TU Dresden

SPDX-License-Identifier: CC-BY-4.0
-->

# Nfdi4earth Knowledge Hub Schema

This repository contains the underlying metadata schema of the NFDI4Earth Knowledge Hub.

The schema is created with [LinkML](https://linkml.io/). Out of the LinkML definition of the schema, we generate several serializations:

- Python bindings to interact with the schema, the generated code is published in the form of a Python package.
- Human-readable documentation of the schema with mkdocs

## Python

### Installation

This package is registered at the [PyPI](https://pypi.org/) registry.

To use this package in another project install it via:

```
pip install nfdi4earth-kh-schema
```

### Deploying new version

To deploy a new version, add a Tag to the latest commit.
Since the env variable holding the token for accesing the pypi API  is set to protected, make sure to add the Tag to the list of protected Tags.
```
Setting → Repository → "Protected Tags"
```

### Development installation

Clone this repository. It is recommended to run it in a Python virtual environment. As a shortcut you can run:

```bash
make venv-init # installs a virtual env and installs this package in development mode.
. venv/bin/activate # activates the virtual env
```

Alternatively, you can install the virtual environment by yourself:

```bash
python -m venv venv
. venv/bin/activate
make dev-install # installs this package in development mode.
```

Note: we are patching the functionality of LinkML in order to accept entities with blank nodes instead of URL identifiers for certain classes (TODO: expand on this)

Finally generate the Python classes from the LinkML definition:

```bash
make generate-python
```

**Important**: After every change in the `n4eschema-linkml.yaml` file, you need to run `make generate-python` (make sure that your virtual environment is activated, see above) again, in order to reflect the updated schema in the Python package! 

To update `schema.json`, run `make generate-json-schema-kh`. Alternatively, run `make dist` to update the Python package, `schema.json`, and `context.jsonld`.



[source code]: https://git.rwth-aachen.de/nfdi4earth/knowledgehub/nfdi4earth-kh-schema
[docs]: https://nfdi4earth.pages.rwth-aachen.de/knowledgehub/nfdi4earth-kh-schema/

## Generation of docs

The functionality of LinkML is used to automatically generate a human-readable documentation of the KH schema, which is based on [mkdocs](https://www.mkdocs.org/). Thus, ensure that the packages `mkdocs`, `mkdocs-material`, and `mkdocs-mermaid2-plugin` are installed in addition to the requirements. 

The generated docs are currently hosted at https://nfdi4earth.pages.rwth-aachen.de/knowledgehub/nfdi4earth-kh-schema/ - see the `.gitlab-ci.yml` file for the workflow.

### Locally build the docs

To test the generated documentation locally, run

```bash
# this initializes a Python virtual environment in the folder "venv" and installs the dependencies there
make venv-init
# activate the virtual environment
source venv/bin/activate
# build the docs based on the LinkML schema
make docs-build
# now try out via localhost
mkdocs serve
# access the static pages via your browser under the displayed url, usually http://127.0.0.1:8000/
```

The docs are currently making use of the `material` [theme for mkdocs](https://squidfunk.github.io/mkdocs-material/). This and other configs can be changed in the `mkdocs.yml`.

## Build and release

A new package is published in gitlab for every release, for this do:

```bash
git tag -a v0.4.x -m "describe changes..."
git push origin --tags
```

## Technical note

This package has been generated from the template
<https://git.rwth-aachen.de/nfdi4earth/architecture/python-package-template> (NOTE: several changes have been made to this package afterwards so it might be out of sync with the template).

See the template repository for instructions on how to update the skeleton for
this package.

## License information

Copyright © 2023 Senckenberg Society for Nature Research, TU Dresden

Licensed under the Apache-2.0

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the Apache-2.0 license for more details.

### License management

License management is handled with [`reuse`](https://reuse.readthedocs.io/).

Contributors: Jonas Grieb, Ralf Klammer, Daniel Nüst
