# datawhalechina/free-excel architecture

> Architecture diagram of the GitHub repository datawhalechina/free-excel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datawhalechina/free-excel
- Repository: https://github.com/datawhalechina/free-excel

## Overview

1. **Repository purpose**
   - This is not an application backend or service; it is a courseware repository for “Free-Excel,” a structured Excel/data-analysis tutorial.
   - The main architectural concern is content production and publication, not runtime behavior.

2. **Primary content model**
   - The tutorial is organized into 10 chapters plus front matter, with parallel chapter files such as `chap1` through `chap10`.
   - Each chapter combines explanatory text with exercise-oriented examples, aiming at practical Excel usage rather than abstract feature reference.

3. **Authoring sources**
   - The editable source lives mainly in `source/` as reStructuredText (`.rst`) files for Sphinx.
   - A second authoring view exists in `Markdown/`, which mirrors the same course structure in Markdown form.
   - These are the human-maintained inputs; everything else is derived or published output.

4. **Build and publishing pipeline**
   - `source/conf.py` and the `source/` tree define a Sphinx documentation project.
   - The `docs/` directory is the generated static website output from that Sphinx build.
   - This means the repository has a clear separation between source content and deployable site artifacts.

5. **Web documentation subsystem**
   - `docs/` contains the published HTML site, search index, static assets, and generated source references.
   - Chapter pages appear under `docs/Content/`, with navigation and landing pages at `docs/index.html` and related localized pages.
   - This is the delivery boundary for online reading.

6. **Markdown course subsystem**
   - `Markdown/` contains the same course in a Markdown-centric format, including chapter files and supporting pages like homepage and author info.
   - This likely serves readers or contributors who prefer Markdown, and may also act as an intermediate or alternate publishing source.
   - It is structurally parallel to the Sphinx source, but separate from the generated HTML site.

7. **Data asset subsystem**
   - `data/` holds chapter-specific sample files used by the lessons, mostly Excel workbooks plus CSV/TXT files.
   - The data is organized by chapter, which suggests each chapter’s examples and exercises depend on a fixed dataset bundle.
   - These files are part of the learning inputs rather than application runtime data.

8. **Content-to-data coupling**
   - Chapter narratives refer to corresponding files in `data/chapX/`, making the learning flow “chapter text → sample dataset → Excel operation.”
   - Chapter 1 is notable for having multiple Titanic-format examples (`csv`, tab-delimited text, special-delimited text, and Excel), showing that data-format teaching is a core theme.

9. **Historical version boundary**
   - `历史版本/V2.0/` preserves an older release of the course, including its own Markdown source and image assets.
   - This is a versioned archival subsystem, not part of the active build, but useful for tracking content evolution.

10. **Documentation assets and static dependencies**
   - `source/_static/` and `docs/_static/` contain Sphinx static resources, theme assets, and supporting CSS/JS.
   - `docs/_images/`, `_sources/`, and `doctrees/` are build artifacts supporting rendering, source linking, and incremental documentation generation.

11. **Repository structure at a glance**
   - Input layer: `source/`, `Markdown/`, `data/`
   - Build layer: Sphinx configuration in `source/conf.py`
   - Output layer: `docs/`
   - Archive layer: `历史版本/`
   - This is the key architectural separation for diagramming the project.

12. **External/environment assumptions**
   - The tutorial is designed around Excel 2016/2019 and optionally WPS for compatibility.
   - That spreadsheet application is the real “execution environment” for the course examples, while the repository itself only distributes instructional content and datasets.

13. **What matters most in an architecture diagram**
   - Show two authoring paths feeding a publication pipeline: Markdown and Sphinx/rST content.
   - Show chapter-linked sample datasets as supporting inputs to the lessons.
   - Show `docs/` as the generated website boundary and `历史版本/` as the frozen legacy branch.

Main entry points: [`docs/Content/chap1.html`](https://github.com/datawhalechina/free-excel/blob/main/docs/Content/chap1.html) (Chapter pages), [`Markdown/chap1.md`](https://github.com/datawhalechina/free-excel/blob/main/Markdown/chap1.md) (Markdown chapters), [`source/Content/chap1.rst`](https://github.com/datawhalechina/free-excel/blob/main/source/Content/chap1.rst) (Chapters rST), [`source/Content/index.rst`](https://github.com/datawhalechina/free-excel/blob/main/source/Content/index.rst) (Content index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Authoring"]
  node_root_index["Front matter<br/>docs entry<br/>[index.rst]"]
  node_content_index["Content index<br/>toc source<br/>[index.rst]"]
  node_chapters_rst["Chapters rST<br/>course source<br/>[chap1.rst]"]
  node_markdown_home["Markdown home<br/>alt source<br/>[主页.md]"]
  node_markdown_chapters["Markdown chapters<br/>alt source<br/>[chap1.md]"]
  node_markdown_notes["Guide pages<br/>support pages<br/>[作者.md]"]
end

subgraph group_build["Build"]
  node_sphinx_conf["Sphinx config<br/>build config<br/>[conf.py]"]
  node_site_sources["Source refs<br/>build refs"]
  node_site_doctrees["Doctrees<br/>sphinx cache"]
end

subgraph group_delivery["Delivery"]
  node_site_index["Site index<br/>html landing<br/>[index.html]"]
  node_site_chapters["Chapter pages<br/>html content<br/>[chap1.html]"]
  node_site_assets["Static assets<br/>web assets"]
end

subgraph group_data["Data"]
  node_data_ch1[("Chapter 1 data<br/>lesson data")]
  node_data_bundle[("Chapter data<br/>lesson data")]
end

subgraph group_archive["Archive"]
  node_legacy_root["V2.0 archive<br/>legacy release<br/>[V2.0]"]
  node_legacy_chapters["Legacy chapters<br/>legacy source<br/>[0. 前言.md]"]
  node_legacy_images["Legacy images<br/>legacy assets<br/>[images]"]
end

node_root_index -->|"navigates"| node_content_index
node_content_index -->|"organizes"| node_chapters_rst
node_sphinx_conf -->|"builds"| node_site_index
node_chapters_rst -->|"renders"| node_site_chapters
node_content_index -->|"publishes"| node_site_chapters
node_site_index -->|"links"| node_site_chapters
node_site_chapters -->|"depends on"| node_site_assets
node_site_chapters -->|"references"| node_site_sources
node_site_chapters -.->|"uses"| node_site_doctrees
node_markdown_home -->|"introduces"| node_markdown_chapters
node_markdown_notes -.->|"supports"| node_markdown_chapters
node_markdown_chapters -->|"exercises"| node_data_ch1
node_chapters_rst -->|"uses"| node_data_bundle
node_legacy_root -->|"contains"| node_legacy_chapters
node_legacy_root -->|"contains"| node_legacy_images
node_chapters_rst -.->|"mirrors"| node_markdown_chapters
node_markdown_chapters -.->|"evolves from"| node_legacy_chapters

click node_root_index "https://github.com/datawhalechina/free-excel/blob/main/source/index.rst"
click node_sphinx_conf "https://github.com/datawhalechina/free-excel/blob/main/source/conf.py"
click node_content_index "https://github.com/datawhalechina/free-excel/blob/main/source/Content/index.rst"
click node_chapters_rst "https://github.com/datawhalechina/free-excel/blob/main/source/Content/chap1.rst"
click node_site_index "https://github.com/datawhalechina/free-excel/blob/main/docs/index.html"
click node_site_chapters "https://github.com/datawhalechina/free-excel/blob/main/docs/Content/chap1.html"
click node_site_assets "https://github.com/datawhalechina/free-excel/tree/main/docs/_static"
click node_site_sources "https://github.com/datawhalechina/free-excel/tree/main/docs/_sources"
click node_site_doctrees "https://github.com/datawhalechina/free-excel/tree/main/docs/doctrees"
click node_markdown_home "https://github.com/datawhalechina/free-excel/blob/main/Markdown/主页.md"
click node_markdown_chapters "https://github.com/datawhalechina/free-excel/blob/main/Markdown/chap1.md"
click node_markdown_notes "https://github.com/datawhalechina/free-excel/blob/main/Markdown/作者.md"
click node_data_ch1 "https://github.com/datawhalechina/free-excel/tree/main/data/chap1"
click node_data_bundle "https://github.com/datawhalechina/free-excel/tree/main/data/chap2"
click node_legacy_root "https://github.com/datawhalechina/free-excel/blob/main/历史版本/V2.0"
click node_legacy_chapters "https://github.com/datawhalechina/free-excel/blob/main/历史版本/V2.0/0. 前言.md"
click node_legacy_images "https://github.com/datawhalechina/free-excel/blob/main/历史版本/V2.0/images"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_index,node_content_index,node_chapters_rst,node_markdown_home,node_markdown_chapters,node_markdown_notes toneBlue
class node_sphinx_conf,node_site_sources,node_site_doctrees toneAmber
class node_site_index,node_site_chapters,node_site_assets toneMint
class node_data_ch1,node_data_bundle toneRose
class node_legacy_root,node_legacy_chapters,node_legacy_images toneIndigo
```

## Components

### Authoring

Human-maintained course sources

- [Front matter](https://github.com/datawhalechina/free-excel/blob/main/source/index.rst): docs entry · Repository landing and publication index · `source/index.rst`
- [Content index](https://github.com/datawhalechina/free-excel/blob/main/source/Content/index.rst): toc source · Chapter table of contents and ordering · `source/Content/index.rst`
- [Chapters rST](https://github.com/datawhalechina/free-excel/blob/main/source/Content/chap1.rst): course source · Primary chapter narratives in reStructuredText · `source/Content/chap1.rst`
- [Markdown home](https://github.com/datawhalechina/free-excel/blob/main/Markdown/主页.md): alt source · Markdown course landing page · `Markdown/主页.md`
- [Markdown chapters](https://github.com/datawhalechina/free-excel/blob/main/Markdown/chap1.md): alt source · Parallel Markdown version of the course chapters · `Markdown/chap1.md`
- [Guide pages](https://github.com/datawhalechina/free-excel/blob/main/Markdown/作者.md): support pages · Auxiliary Markdown pages for author and exercise guidance · `Markdown/作者.md`

### Build

Sphinx configuration and generated artifacts

- [Sphinx config](https://github.com/datawhalechina/free-excel/blob/main/source/conf.py): build config · Documentation build configuration · `source/conf.py`
- [Source refs](https://github.com/datawhalechina/free-excel/tree/main/docs/_sources): build refs · Generated source backreferences for published pages · `docs/_sources`
- [Doctrees](https://github.com/datawhalechina/free-excel/tree/main/docs/doctrees): sphinx cache · Incremental build cache and environment state · `docs/doctrees`

### Delivery

Published website output

- [Site index](https://github.com/datawhalechina/free-excel/blob/main/docs/index.html): html landing · Published documentation landing page · `docs/index.html`
- [Chapter pages](https://github.com/datawhalechina/free-excel/blob/main/docs/Content/chap1.html): html content · Rendered chapter pages for online reading · `docs/Content/chap1.html`
- [Static assets](https://github.com/datawhalechina/free-excel/tree/main/docs/_static): web assets · Theme, CSS, JS, and supporting static files · `docs/_static`

### Data

Lesson datasets and examples

- [Chapter 1 data](https://github.com/datawhalechina/free-excel/tree/main/data/chap1): lesson data · Sample workbooks and text files for chapter 1 · `data/chap1`
- [Chapter data](https://github.com/datawhalechina/free-excel/tree/main/data/chap2): lesson data · Chapter-aligned example datasets across the course · `data/chap2`

### Archive

Frozen historical release

- [V2.0 archive](https://github.com/datawhalechina/free-excel/blob/main/历史版本/V2.0): legacy release · Frozen previous course release · `历史版本/V2.0`
- [Legacy chapters](https://github.com/datawhalechina/free-excel/blob/HEAD/%E5%8E%86%E5%8F%B2%E7%89%88%E6%9C%AC/V2.0/0.%20%E5%89%8D%E8%A8%80.md): legacy source · Archived Markdown course content from the older release · `历史版本/V2.0/0. 前言.md`
- [Legacy images](https://github.com/datawhalechina/free-excel/blob/main/历史版本/V2.0/images): legacy assets · Archived chapter image assets · `历史版本/V2.0/images`

## Connections

- Front matter → Content index: navigates · Landing page points into the chapter structure
- Content index → Chapters rST: organizes · Chapter ordering is defined by the content index
- Sphinx config → Site index: builds · Sphinx configuration produces the published site
- Chapters rST → Chapter pages: renders · Chapter source is rendered into HTML pages
- Content index → Chapter pages: publishes · Table of contents drives the generated chapter pages
- Site index → Chapter pages: links · The landing page routes readers through the chapter pages
- Chapter pages → Static assets: depends on · Rendered pages rely on shared static assets
- Chapter pages → Source refs: references · Published pages expose generated source references
- Chapter pages → Doctrees: uses · Incremental documentation state supports the build
- Markdown home → Markdown chapters: introduces · Markdown landing content leads into the chapter set
- Guide pages → Markdown chapters: supports · Auxiliary pages accompany the Markdown course path
- Markdown chapters → Chapter 1 data: exercises · Lessons pair with chapter-specific sample files
- Chapters rST → Chapter data: uses · Chapter narratives refer to chapter-aligned datasets
- V2.0 archive → Legacy chapters: contains · Older release preserves its own course sources
- V2.0 archive → Legacy images: contains · Archived release includes its associated image assets
- Chapters rST → Markdown chapters: mirrors · The two authoring paths track the same chapter structure
- Markdown chapters → Legacy chapters: evolves from · Archived release shows an earlier content branch