# pyopensci/python-packaging-guide architecture

> Architecture diagram of the GitHub repository pyopensci/python-packaging-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pyopensci/python-packaging-guide
- Repository: https://github.com/pyopensci/python-packaging-guide

## Overview

##### Project type and purpose
- This is a static‐site documentation project (“pyOpenSci Python Packaging Guide”) built with Sphinx, orchestrated by nox.
- Purpose: provide multi‐language tutorials and best practices on Python packaging, with translation and CI workflows.

##### File structure
- Top‐level directories:
- documentation content: `index.md`, `tutorials/`, `documentation/`, `package-structure-code/`, `tests/`, `continuous-integration/`
- Sphinx config and sources: `conf.py`, `_ext/` (custom Sphinx extensions), `_templates/`, `_static/`, `bibliography.bib`
- Examples: `examples/`
- Localization: `locales/`
- CI/build configs: `noxfile.py`, `.github/workflows/`, `.circleci/config.yml`, `crowdin.yml`
- Key patterns:
- Static Site Generation (SSG) via Sphinx
- Automated builds/test via nox and CI pipelines (GitHub Actions & CircleCI)
- Translation workflow via Crowdin

##### README for additional insights
- Build steps: use `nox -s docs` and `nox -s docs-live` to generate `.nox` env and HTML in `_build/html`
- Build modes: `development` builds all languages; `production` filters by `release_languages`
- CI workflows for building, testing, publishing

##### Detailed Capturing of Architectural Elements
- `conf.py` & `_ext/` as the Sphinx engine’s plugin layer
- CI configs in `.github/workflows/` and `.circleci/config.yml` invoking nox
- Environment variables (SPHINX_ENV) controlling build modes
- Live‐reload for local development vs. production artifact generation

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Repository
    subgraph "Source Repository" 
        direction TB
        Content["Documentation Content"]:::code
        Tutorials["Tutorials"]:::code
        PackageCode["Package Structure Code"]:::code
        Examples["Examples"]:::code
        Tests["Tests"]:::code
        CIContent["CI Content"]:::code
        Index["index.md"]:::code
    end

    %% Sphinx Configuration
    subgraph "Sphinx Configuration" 
        direction TB
        Conf["conf.py"]:::code
        Extensions["Custom Extensions"]:::code
        Templates["Templates"]:::code
        StaticAssets["Static Assets"]:::code
        Bibliography["bibliography.bib"]:::code
        RSS["rss.py"]:::code
        TransGraph["translation_graph.py"]:::code
    end

    %% Build Orchestration
    subgraph "Build Orchestration" 
        direction TB
        Noxfile["noxfile.py"]:::build
    end

    %% Build Tools
    subgraph "Build Tools" 
        direction TB
        Nox["nox Sessions"]:::build
        Sphinx["Sphinx Engine"]:::build
    end

    %% Localization Service
    subgraph "Localization Service" 
        direction TB
        CrowdinCfg["crowdin.yml"]:::external
        Locales["locales/"]:::code
    end

    %% Continuous Integration
    subgraph "Continuous Integration" 
        direction TB
        GHMain["main.yml"]:::build
        GHBook["build-book.yml"]:::build
        GHCrowdin["crowdin_sync.yml"]:::build
        GHArtifact["artifact_redirect.yml"]:::build
        CircleCI[".circleci/config.yml"]:::build
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        Zenodo[".zenodo.json"]:::external
    end

    %% Output & Hosting
    subgraph "Output & Hosting" 
        direction TB
        HTML["_build/html"]:::output
        Hosting["GitHub Pages"]:::output
    end

    %% Relationships
    Content -->|commits| Noxfile
    Tutorials --> Noxfile
    PackageCode --> Noxfile
    Examples --> Noxfile
    Tests --> Noxfile
    CIContent --> Noxfile
    Index --> Noxfile

    Noxfile -->|defines sessions| Nox
    Nox -->|invokes| Sphinx
    Conf --> Sphinx
    Extensions --> Sphinx
    Templates --> Sphinx
    StaticAssets --> Sphinx
    Bibliography --> Sphinx
    RSS --> Extensions
    TransGraph --> Extensions

    CrowdinCfg -->|syncs| Locales
    Locales --> Sphinx

    GHMain --> Nox
    GHBook --> Nox
    GHCrowdin --> CrowdinCfg
    GHArtifact --> HTML
    CircleCI --> Nox

    Sphinx --> HTML
    HTML --> Hosting
    Zenodo -->|badge in| Index

    %% Click Events
    click Content "https://github.com/pyopensci/python-packaging-guide/tree/main/documentation/"
    click Tutorials "https://github.com/pyopensci/python-packaging-guide/tree/main/tutorials/"
    click PackageCode "https://github.com/pyopensci/python-packaging-guide/tree/main/package-structure-code/"
    click Examples "https://github.com/pyopensci/python-packaging-guide/tree/main/examples/"
    click Tests "https://github.com/pyopensci/python-packaging-guide/tree/main/tests/"
    click CIContent "https://github.com/pyopensci/python-packaging-guide/tree/main/continuous-integration/"
    click Index "https://github.com/pyopensci/python-packaging-guide/blob/main/index.md"
    click Conf "https://github.com/pyopensci/python-packaging-guide/blob/main/conf.py"
    click Extensions "https://github.com/pyopensci/python-packaging-guide/tree/main/_ext/"
    click Templates "https://github.com/pyopensci/python-packaging-guide/tree/main/_templates/"
    click StaticAssets "https://github.com/pyopensci/python-packaging-guide/tree/main/_static/"
    click Bibliography "https://github.com/pyopensci/python-packaging-guide/blob/main/bibliography.bib"
    click RSS "https://github.com/pyopensci/python-packaging-guide/blob/main/_ext/rss.py"
    click TransGraph "https://github.com/pyopensci/python-packaging-guide/blob/main/_ext/translation_graph.py"
    click Noxfile "https://github.com/pyopensci/python-packaging-guide/blob/main/noxfile.py"
    click CrowdinCfg "https://github.com/pyopensci/python-packaging-guide/blob/main/crowdin.yml"
    click Locales "https://github.com/pyopensci/python-packaging-guide/tree/main/locales/"
    click GHMain "https://github.com/pyopensci/python-packaging-guide/blob/main/.github/workflows/main.yml"
    click GHBook "https://github.com/pyopensci/python-packaging-guide/blob/main/.github/workflows/build-book.yml"
    click GHCrowdin "https://github.com/pyopensci/python-packaging-guide/blob/main/.github/workflows/crowdin_sync.yml"
    click GHArtifact "https://github.com/pyopensci/python-packaging-guide/blob/main/.github/workflows/artifact_redirect.yml"
    click CircleCI "https://github.com/pyopensci/python-packaging-guide/blob/main/.circleci/config.yml"
    click Zenodo "https://github.com/pyopensci/python-packaging-guide/blob/main/.zenodo.json"

    %% Styles
    classDef code fill:#D0E6FF,stroke:#005A9C,color:#005A9C;
    classDef build fill:#DFF2BF,stroke:#4F8A10,color:#4F8A10;
    classDef external fill:#FFE0B2,stroke:#BF360C,color:#BF360C;
    classDef output fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A;
```
