How noviscient/factsheet-wiki works
Project Type and Purpose
• This is an open-source documentation site (“Factsheet-Wiki”) built with MkDocs and intended to explain the code and formulas behind a financial factsheet generation library. It produces a static HTML site (hosted via ReadTheDocs or GitHub Pages) containing the README and additional content in the docs/ folder.
File Structure Analysis
• Top‐level config files:
• .readthedocs.yaml – ReadTheDocs build configuration
• mkdocs.yml – MkDocs site configuration
• pyproject.toml – Python packaging metadata
• Content:
• README.md – Landing page and detailed table of contents/formulas
• docs/index.md – Main MkDocs landing page content
• docs/requirements.txt – Python dependencies for docs
• No src/ or code directories: this repo purely generates documentation (the actual calculation.py, plotting.py live elsewhere or are imported).
a. Main Components
1. Authoring Environment (local machine)
– Markdown source: README.md + docs/*.md
– Configuration: mkdocs.yml, pyproject.toml
– Dependencies: docs/requirements.txt
2. Build Engine
– MkDocs (Python static site generator)
– ReadTheDocs build service (CI/CD)
3. Artifact
– Static HTML/CSS/JS site
4. Hosting / Delivery
– ReadTheDocs server or GitHub Pages
– End-user (browser)
b. Relationships and Data Flow
1. Developer writes Markdown under docs/ and README.md
→ mkdocs.yml config instructs MkDocs how to structure navigation and theme
2. mkdocs build (locally or CI)
→ parses Markdown + config → outputs static site files
3. CI (ReadTheDocs or GitHub Actions)
– triggered on push → installs docs/requirements.txt → runs mkdocs build → deploys to hosting
4. End-user requests docs site
→ ReadTheDocs / GitHub Pages serves static assets
c. Architectural Patterns / Design Principles
• Static Site Generator pattern: source files → build → static output
• CI/CD pipeline for documentation: “docs as code” best practice
• Single-page application style navigation via MkDocs theme
d. Key Technologies and Libraries
• MkDocs (Python)
• Markdown (.md files)
• Python packaging (PEP 517 pyproject.toml)
• ReadTheDocs / GitHub Pages for hosting
• CI/CD: ReadTheDocs build or GitHub Actions (implied)