# odoo/documentation architecture

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

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

## Overview

##### Main Components
- Content Repository: The “content” folder holds thousands of reStructuredText (RST) files organized by topics like Administration, Applications (with various subdirectories for modules such as Sales, HR, Inventory, etc.), Developer documentation, Legal and Contributing. This forms the core documentation content.
- Build/Configuration Layer: Files such as “conf.py”, “Makefile”, and “requirements.txt” provide the Sphinx configuration, build instructions, and dependency listing. s This is responsible for converting RST source files into HTML (and other formats).
- Extensions and Custom Plugins: The “extensions” directory contains several custom Sphinx extensions (for things like autodoc fields, custom admonitions, embedded video, Github links, and custom theme modifications via the “odoo_theme” module). These integrate into the build pipeline through the configuration.
- Static Assets: The “static” folder (with its subfolders for CSS, JavaScript, images, and even LaTeX support) holds theme assets, styling, and static files that are referenced during the build process.
- Localization Files: The “locale” directory holds numerous translation files (.po and .pot) for various languages – essential to support community translation and internationalization.
- Redirects: Managed in the “redirects” folder, these files likely facilitate URL changes between documentation versions.
- Testing Suite: In the “tests” directory you have checker scripts (such as “redirect_rules.py”, “rst_style.py”) that are run to ensure documentation quality and consistency.

##### Relationships and Data Flow
– Content Files (RST) → Sphinx Build Process via conf.py/Makefile.
– Static Assets are merged during the build to produce the final website.
- Localization files (locale) are integrated into the process to produce translated outputs.
- Redirect files provide post-processing or mapping to handle URL changes across documentation versions.
- The testing suite runs against the documentation build process to check for style, broken links, and redirection rules.

##### Architectural Patterns and Design Principles
- Modular Design: The project is broken down by thematic and function-based modules (content, extensions, tests, static, locale). Emphasize how each module is responsible for a defined aspect of the documentation architecture.
- Separation of Concerns: Content creation is separated from the build configuration and customization (extensions), and further, from testing. This design makes maintenance easier.
- Integration Points: The custom Sphinx extensions integrate at specific build hooks within the Sphinx pipeline, so they are key integration points.
- Use of Standard Tools: The process leverages standard technologies (Python, Sphinx, Make, and standard static assets management) which are fundamental to many documentation builds.

##### Relevant Technologies and Frameworks
- Sphinx: The core framework for converting RST into built artifacts.
- Python: The scripting language used for Sphinx and running build or test scripts.
- Make: The build system orchestrating the conversion process.
- Custom Sphinx Extensions: Provided in the “extensions” folder, which include modules for enhancing functionality.
- CSS, JavaScript, LaTeX: Assets used to style and format documentation outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content & Localization Layer"
        CT["Content (RST Files)"]:::content
        LO["Localization Files"]:::content
    end

    subgraph "Build Layer"
        M["Makefile"]:::build
        CP["conf.py"]:::build
        RT["requirements.txt"]:::build
        EX["Custom Extensions"]:::build
        SE["Sphinx Build Engine"]:::build
    end

    subgraph "Asset Layer"
        AS["Static Assets"]:::asset
    end

    subgraph "Verification Layer"
        TS["Testing Suite"]:::test
        RR["Redirect Rules"]:::test
    end

    %% Data Flow Connections
    CT -->|"sources"| SE
    LO -->|"translations"| SE
    M -->|"config"| SE
    CP -->|"config"| SE
    RT -->|"dependencies"| SE
    EX -->|"extensions"| SE
    SE -->|"build_output"| FO["Documentation Website (HTML)"]:::output
    AS -->|"assets_merged"| FO
    TS -->|"quality_check"| SE
    RR -->|"redirects_applied"| FO

    %% Click Events
    click CT "https://github.com/odoo/documentation/tree/18.0/content/"
    click M "https://github.com/odoo/documentation/tree/18.0/Makefile"
    click CP "https://github.com/odoo/documentation/blob/18.0/conf.py"
    click RT "https://github.com/odoo/documentation/blob/18.0/requirements.txt"
    click EX "https://github.com/odoo/documentation/tree/18.0/extensions/"
    click AS "https://github.com/odoo/documentation/tree/18.0/static/"
    click LO "https://github.com/odoo/documentation/tree/18.0/locale/"
    click RR "https://github.com/odoo/documentation/tree/18.0/redirects/"
    click TS "https://github.com/odoo/documentation/tree/18.0/tests/"

    %% Styling
    classDef content fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef build fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef asset fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef test fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef output fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
