nomad-docs

This repository hosts all official documentation for the NOMAD platform — including user guides, developer docs, and API references. It supports both users and developers working with NOMAD and NOMAD Oasis.

See the releases for different versions of the documentation (from v1.4.0 onwards they are synced with NOMAD versions).

Contributing

• Typos, corrections, and missing docs can be reported by Creating an Issue

• For internal contributions (write access to the repo required), please open a pull request (PR) with your changes. At least one review from a FAIRmat co-worker is required before merging. If you are not sure who to assign, please ask in the PR conversation by tagging @ahm531 or @JFRudzinski.

• For external contributions, please follow the External Contribution Instructions

• Any contributions that should end up in the next documentation release should target the develop branch. When a new version of the NOMAD software is released, the current state of the develop branch will be merged into main with a corresponding version tag: this way the documentation can be synced with NOMAD versions. Note that you should not merge documentation for features that will not be included in the next release: keep them in another branch.

Writing Guide

When contributing, please check the writing guide for best practices.

---

Running the Docs Server Locally

If you have a nomad-dev-distro setup, you can follow the day to day development instructions to install nomad-docs as a submodule there.

If you do not have an up-to-date Python installation (3.11 or 3.12), see Help to install Python below.

1. Install uv

(a) Standalone

On macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If installed via the standalone installer, uv can update itself to the latest version:

uv self update

Or, from PyPI:

(b) With pip

pip install uv

(c) With pipx

pipx install uv

2. Run the Local Docs Server

Once uv is installed, you can start the MkDocs server with:

uv run mkdocs serve

This will install all requirements in a virtual environment and start the local development server.

💡 Tip: To compare your local docs with the latest version once you start making significant changes, use the DEV Deployment DOCS.

How to run the tests

uv run --extra dev pytest

---

Automated Tests

This repository uses GitHub Actions to automatically run a series of tests on every push and pull request to the main branch. These tests ensure the quality and integrity of the documentation.

1. Link Check

This test checks for broken links in all markdown files (.md) within the docs and examples directories, as well as in the README.md file. This ensures that all internal and external links are valid and accessible.

2. Documentation Build

This test builds the MkDocs documentation using the --strict flag. This flag treats any warnings as errors, ensuring that the documentation is always in a buildable state.

3. Pytest

This test runs the pytest command to execute all the tests in the tests directory. This test runs the pytest command to execute all the tests in the tests directory. These tests include:

• test_assets.py: This test ensures there are no unused assets (e.g., images, data files) in the docs/ directory by checking if they are referenced in any Markdown files.
• test_docs.py: This test verifies that the documentation pages are served correctly, checking for proper HTTP status codes and cache headers.
• test_pydantic.py: This test checks helper functions that extract information from Pydantic models, which are used to automatically generate documentation for these models.
• test_metainfo.py: This test checks helper functions that extract information from NOMAD's Metainfo models, which are used to automatically generate documentation for these models.

---

Appendix

External Contribution Instructions

1. Fork the Repository

Click the Fork button at the top right of this page to create a copy of the repo under your GitHub account.

2. Clone Your Fork Locally

git clone https://github.com/your-username/nomad-docs.git
cd nomad-docs

3. Create a New Branch for Your Changes

git checkout -b my-feature-branch

4. Make and Commit Your Changes

5. Push to Your Fork

git push origin my-feature-branch

6. Open a Pull Request

• Go to your fork on GitHub.
• Click "Compare & pull request".
• Choose the base repo (FAIRmat-NFDI/nomad-docs) and target branch (e.g., develop).
• Describe your changes and submit the PR.

✅ Your PR will be reviewed by the maintainers. You don’t need write access to contribute this way.

---

Help to install Python 3.11 or 3.12

Note: Replace 3.11 with 3.12 below if you prefer to use Python 3.12.

If Python 3.11 is not installed on your system, use the instructions below based on your OS:

Debian Linux

sudo apt install python3.11

Red Hat Linux

sudo dnf install python3.11

macOS

brew install python@3.11

Windows PowerShell

1. Download the installer from the official Python website.
2. Run the installer.
3. Make sure to check the box "Add Python 3.11 to PATH" during installation.