README.md

Simulation Systems

This repository contains the working practices documentation common to the various simulation and modelling repositories owned by the Met Office.

Repositories

Access	Repos
Open Source	casim, lfric_apps, lfric_core, moci, monc, mule, rose_picker, shumlib, socrates-spectral, socrates, ukca
Private	gcom, jules, jules-internal, um, um_aux, um_doc, um_meta

---

The documentation in the repository can be compiled in different ways.

Note

Optional system dependencies for PDF generation may require LaTeX distributions and other third-party libraries.

Setup environment

You can set up the environment ro build and deploy the documentation using any of the following methods:

1. Using uv

A quick and clean way to get the package dependencies is via the uv package manager.

git clone https://github.com/MetOffice/simulation-systems
cd simulation-systems

# Install dependencies (see pyproject.toml) in project .venv
uv sync

2. Using pip

If you have Python 3.11 or higher installed (sphinx==8.2.3 required), you can use pip:

git clone https://github.com/MetOffice/simulation-systems
cd simulation-systems

<path/to/python3.11+> -m venv .venv
source .venv/bin/activate
pip install .

3. Using conda

git clone https://github.com/MetOffice/simulation-systems
cd simulation-systems

conda env create -f env.yml
conda activate sphinx_doc_env

Build documentation

# For uv environment
uv run make clean html

# For pip or conda environments
make clean html

After building, the HTML documentation can be found in the build/html/ directory of your local repository. You can open the documentation in any web browser.

Met Office users can skip build step above and deploy the documentation directly to a predefined location: ~/public_html/simulation-systems/<branch-name>/html/

uv run make clean deploy  # uv env
# OR
make clean deploy  # pip or conda env

Contributing

Please follow the project's Code of Conduct

The documentation is written in Sphinx markup. To propose changes:

1. Create an issue detailing the required changes.
2. Create a branch in your clone of this repository, linking it to your issue.
3. Regularly build your changes as described above.

Once satisfied, create a pull request and request a review from MetOffice/ssdteam.