datawhalechina/free-excel

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.