Skip to content
Snippets Groups Projects

Added a new code contribution guide to the docs.

Merged Markus Scheidgen requested to merge documentation into develop
6 files
+ 375
2
Compare changes
  • Side-by-side
  • Inline
Files
6
+ 73
0
 
NOMAD is a complex project with lots of parts. This guide gives you a rough overview
 
about the code-base and ideas to what to look at first.
 
 
## Git Projects
 
 
There is one [main NOMAD project](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR)
 
(and its [fork on GitHub](https://github.com/nomad-coe/nomad)). This project contains
 
all the framework and infrastructure code. It instigates all checks, builds, and deployments
 
for the public NOMAD service, the NOMAD Oasis, and the `nomad-lab` Python package. All
 
contributions to NOMAD have to go through this project eventually.
 
 
All (Git) projects that NOMAD depends on are either a Git submodule (you find
 
them all in the `/dependencies` directory or its subdirectories) or they are
 
listed as PyPI packages in the `/pyproject.toml` of the main project (or one of its
 
submodules).
 
 
You can also have a look at the [list of parsers](../reference/parsers.md) and [built-in plugins](../reference/plugins.md)
 
that constitute the majority of these projects. The only other projects are
 
[matid](https://github.com/SINGROUP/matid), [density of state fingerprints](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-dos-fingerprints), and the [NOMAD Remote Tools Hub tools](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-remote-tools-hub).
 
 
!!! note
 
The GitLab organization [nomad-lab](https://gitlab.mpcdf.mpg.de/nomad-lab) and the GitHub organizations for [FAIRmat](https://github.com/fairmat-nfdi) and
 
the [NOMAD CoE](https://github.com/nomad-coe) all represent larger infrastructure and research projects, and
 
they include many other Git projects that are not related. When navigating the
 
code-base only follow the submodules.
 
 
## Python code
 
 
There are three main directories with Python code:
 
 
- `/nomad`: The actual NOMAD code. It is structured into more subdirectories and modules.
 
- `/tests`: Tests ([pytest](https://docs.pytest.org)) for the NOMAD code. It follows the same module structure, but Python files
 
are prefixed with `test_`.
 
- `/examples`: This contains a few small Python scripts that might be linked in the documentation.
 
 
The `/nomad` directory contains the following "main" modules. This list is not extensive, but
 
should help you to navigate the code base:
 
 
- `config`: NOMAD is configured through the `nomad.yaml` file. This contains all the ([pydantic](https://docs.pydantic.dev/)) models and default config parameters.
 
- `utils`: Somewhat self-explanatory; notable features: the structured logging system ([structlog](https://www.structlog.org/)) and id generation and hashes.
 
- `units`: The unit and unit conversion system based on [Pint](https://pint.readthedocs.io).
 
- `app`: The [fast-api](https://fastapi.tiangolo.com/) APIs: v1 and v1.2 NOMAD APIs, [OPTIMADE](https://www.optimade.org/), [DCAT](https://www.w3.org/TR/vocab-dcat-2/), [h5grove](https://github.com/silx-kit/h5grove), and more.
 
- `cli`: The command line interface (based on [click](https://click.palletsprojects.com)). Subcommands are structured into submodules.
 
- `parsing`: The base classes for parsers, matching functionality, parser initialization, some fundamental parsers like the *archive* parser. See also the docs on [processing](../learn/basics.md#parsing).
 
- `normalizing`: All the normalizers. See also the docs on [processing](../learn/basics.md#normalizing).
 
- `metainfo`: The metainfo system, e.g. the schema language that NOMAD uses.
 
- `datamodel`: The built-in schemas (e.g. `nomad.datamodel.metainfo.simulation` used by all the theory parsers). The base sections and section for the shared entry structure. See also the docs on the [datamodel](../learn/data.md) and [processing](../learn/basics.md).
 
- `search`: The interface to [elasticsearch](https://www.elastic.co/guide/en/enterprise-search/current/start.html).
 
- `processing`: Its all about processing uploads and entries. The interface to [celery](https://docs.celeryq.dev/en/stable/) and [mongodb](https://www.mongodb.com).
 
- `files`: Functionality to main the files for uploads in staging and published. The interface to the file system.
 
- `archive`: Functionality to store and access archive files. This is the storage format for all processed data in nomad. See also the docs on [structured data](../learn/data.md).
 
 
## GUI code
 
 
The NOMAD UI is written as a [react](https://react.dev/) single page application (SPA). It uses (among many other libraries)
 
[MUI](https://mui.com/), [plotly](https://plotly.com/python/), and [D3](https://d3js.org/). The GUI code is maintained in the `/gui` directory. Most relevant code
 
can be found in `/gui/src/components`. The application entrypoint is `/gui/src/index.js`.
 
 
## Documentation
 
 
The documentation is based on [MkDocs](https://www.mkdocs.org/). The important files
 
and directories are:
 
 
- [/docs](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR/-/tree/develop/docs): Contains all the markdown files that contribute to the documentation system.
 
- [/mkdocs.yml](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR/-/tree/develop/mkdocs.yml): The index and configuration of the documentation, new files have to be added here as well.
 
- [/nomad/mkdocs.py](https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR/-/tree/develop/nomad/mkdocs.py): Python code that defines [macros](https://mkdocs-macros-plugin.readthedocs.io/) that can be
 
used in markdown.
 
 
## Other top-level directories
 
 
- `dependencies`: Contains all the submodules (e.g. the parsers).
 
- `ops`: Contains artifacts to run NOMAD components, e.g. docker-compose.yaml files and our kubernetes helm chart.
 
- `scripts`: Contains scripts used during build or for certain development tasks.
 
\ No newline at end of file
Loading