# multimodelling/documentation architecture

> Architecture diagram of the GitHub repository multimodelling/documentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/multimodelling/documentation
- Repository: https://github.com/multimodelling/documentation

## Overview

##### Project type and purpose
- This repository is purely a documentation project built with Sphinx (ReadTheDocs‑style). Its sole purpose is to generate and host the Multimodelling Documentation as a static website on ReadTheDocs.

##### File structure
- Top‑level:
- docs/           ← Sphinx source trees
- requirements.txt
- .readthedocs.yaml, README.md, CONTRIBUTE.md, LICENSE
- Under docs/source/: multiple subfolders organizing content by audience and domain:
- enduser/
- energy_models/
- example_use_cases/
- scientific/
- technical/
- installation/, introduction/, terminology/
- docs/ contains build scripts (Makefile, make.bat) and Sphinx conf.py in docs/source.

##### README for additional insights
- The project is built locally with “make html” in docs/, producing HTML under docs/build/html, and on commit/push ReadTheDocs auto‑builds and hosts the site.

a. Main components to represent
1. Developer Workstation
– Local code checkout (Git)
– docs/ source tree (reStructuredText files, conf.py)
– Local build tooling (Makefile, Python + Sphinx)
2. Version Control (GitHub)
– docs/ and config (.readthedocs.yaml, requirements.txt)
3. Continuous Build Service (ReadTheDocs)
– Pulls from GitHub on each push
– Installs dependencies
– Runs Sphinx build
4. Build Outputs
– HTML files (docs/build/html)
5. Hosting / CDN
– Serves the generated static site at https://multimodelling.readthedocs.io/
b. Relationships & data flows
- Developer edits docs locally → runs `make html` → preview in browser
- Developer pushes to GitHub → Git hook triggers ReadTheDocs build
- ReadTheDocs clones, installs requirements, runs Sphinx → outputs HTML
- ReadTheDocs deploys HTML to the public URL
c. Architectural patterns & design principles
- Static‑site generation pipeline
- Git‑triggered CI/CD (auto‑deploy)
- Modular content organization by audience/domain (folder per section)
d. Relevant technologies
- Sphinx (conf.py, rst files)
- Python (docs dependencies in requirements.txt)
- Make (Makefile, make.bat)
- GitHub (source repo)
- ReadTheDocs (build + hosting)

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Developer Workstation"
        direction TB
        localTree["Local Sphinx Source Tree<br/>docs/source/"]:::local
        conf["Sphinx Configuration<br/>conf.py"]:::local
        makefile["Makefile"]:::local
        makebat["make.bat"]:::local
        
        subgraph "Content Structure"
            direction TB
            enduser["enduser/"]:::local
            energy["energy_models/"]:::local
            example["example_use_cases/"]:::local
            scientific["scientific/"]:::local
            technical["technical/"]:::local
            installation["installation/"]:::local
            introduction["introduction/"]:::local
            terminology["terminology/"]:::local
        end
    end

    subgraph "Version Control (GitHub)"
        direction TB
        repoRoot["Repository Root & Config"]:::repo
        readthedocsYaml[".readthedocs.yaml"]:::repo
        requirements["requirements.txt"]:::repo
        readme["README.md"]:::repo
        gitignore[".gitignore"]:::repo
    end

    CI["ReadTheDocs Build Service"]:::build

    output["Generated HTML<br/>docs/build/html"]:::output

    host["Published Site<br/>multimodelling.readthedocs.io"]:::output

    %% Relationships
    localTree -->|"uses config & tooling"| output
    conf --> output
    makefile --> output
    makebat --> output

    localTree -->|"push changes"| repoRoot
    conf --> repoRoot
    makefile --> repoRoot
    makebat --> repoRoot
    readthedocsYaml --> repoRoot
    requirements --> repoRoot
    readme --> repoRoot
    gitignore --> repoRoot

    repoRoot -->|"trigger build"| CI
    CI -->|"runs Sphinx build"| output
    output -->|"deploy"| host

    %% Click Events
    click localTree "https://github.com/multimodelling/documentation/tree/main/docs/source/"
    click conf "https://github.com/multimodelling/documentation/blob/main/docs/source/conf.py"
    click makefile "https://github.com/multimodelling/documentation/tree/main/docs/Makefile"
    click makebat "https://github.com/multimodelling/documentation/blob/main/docs/make.bat"
    click readthedocsYaml "https://github.com/multimodelling/documentation/blob/main/.readthedocs.yaml"
    click requirements "https://github.com/multimodelling/documentation/blob/main/requirements.txt"
    click readme "https://github.com/multimodelling/documentation/blob/main/README.md"
    click gitignore "https://github.com/multimodelling/documentation/blob/main/.gitignore"
    click enduser "https://github.com/multimodelling/documentation/tree/main/docs/source/enduser/"
    click energy "https://github.com/multimodelling/documentation/tree/main/docs/source/energy_models/"
    click example "https://github.com/multimodelling/documentation/tree/main/docs/source/example_use_cases/"
    click scientific "https://github.com/multimodelling/documentation/tree/main/docs/source/scientific/"
    click technical "https://github.com/multimodelling/documentation/tree/main/docs/source/technical/"
    click installation "https://github.com/multimodelling/documentation/tree/main/docs/source/installation/"
    click introduction "https://github.com/multimodelling/documentation/tree/main/docs/source/introduction/"
    click terminology "https://github.com/multimodelling/documentation/tree/main/docs/source/terminology/"
    click output "https://github.com/multimodelling/documentation/tree/main/docs/build/html/"

    %% Styles
    classDef local fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef repo fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef build fill:#98FB98,stroke:#333,stroke-width:1px
    classDef output fill:#FFD580,stroke:#333,stroke-width:1px
```
