# Structure of the repository This document is intended as a guideline through the *auto-icon* repository. The repository contains a set of directories and a few additional important files. ## Gitlab CI/CD The directory `.gitlab-ci` contains several configuration files relevant for the CI/CD pipelines. It contains - Configurations for the pipelines running at KIT and LMU - Overview of available testcases for KIT pipeline - Config for the documentation pipeline jobs - Config (`job-templates.yml`) and script (`generate-ci-config.sh`) to create the child pipeline running *auto-icon* experiments ## Configuration The directory `conf` contains all (yaml) configuration files. It directly contains a file and corresponding directory for each *ICON case* and additionally a directory with config files common to all cases. Further info is already available in the [User guide](../Userguide/Configuration-files.md#project-conf-subdirectory). ## Documentation The directory `docs` contains all raw files for the documentation, that is created with sphinx in a pipeline and hosted as Gitlab pages. It further contains a makefile and a source subdirectory. The latter then contains several subdirectoires for the chapters and an index. To add something to the documentation, either modify one of the existing files or add a new one. In the latter case, also add the file to the corresponding toctree (in the respective `index.rst` file). Further, you should test if the documentation looks correct by building it locally. You can do so by running `sphinx-build -b html docs/source/ public/` and then opening `public/index.html` in your browser. :::{seealso} Detailed commands to build the documentation are outlined in the CI/CD job (`.gitlab-ci/documentation.yml`) ::: ## Examples The `examples` directory contains a few scripts for running tests of the `build_only`, `real-from-ideal` and `real-from-dwd-ana` test cases and an example for the `platforms_user.yml` configuration. Other examples could be placed here, if necessary. ## Licenses Files with the license texts relevant for *auto-icon* are all placed in the `LICESNSES` directory. ## Namelists All namelist templates are contained here, separated by the *ICON case*, along with a common directory for the master namelist and other miscellaneous namelists. Some cases further have a modified master namelist in their respective directory (e.g. `art` and `seamless`). ## Spack related files Spack related files are contained in the two directories `platforms` and `spack_repo`. Those should not contain other stuff than required for the spack installation. ## Templates The `templates` directory contains all script templates that Autosubmit will execute. If a job shall be modified or a new job added, this is the correct place. There is a `common` subdirectory for jobs shared among the *ICON cases* and further subdirectories for the individual cases. Additionally, there is a `utils` subdirectory containing multiple python modules with utility functions, used accross many jobs. :::{hint} When developing a new python job, always check out the utilities, if there are some existing functions, classes, etc. that can be of use for your purpose. ::: ## Tests The `tests` directory contains a few files for testing beyond the CI pipelines. ## Other files Besides standard (config) files like `.gitignore`, `README.md`, `REUSE.toml`, `ruff.toml`, `.pre-commit-config.yaml` and `.gitlab-ci.yml`, there is also the init script `auto-icon-init.py` and a symlink to it `auto-icon-init`. The init script shall be modified for many changes as it is the main entrypoint for users for new experiments.