How zhuminjie/openseespydoc works
Project Type and Purpose
• This is an open-source documentation site for OpenSeesPy: a Python interpreter of the OpenSees structural analysis framework. It uses Sphinx to collect reStructuredText source files, Python examples, and static assets to produce browsable HTML/PDF documentation, which is then hosted (e.g., on ReadTheDocs).
a. Source Content
• rst files under src/ (API reference, tutorials, command docs)
• index.rst & additional top-level .rst pages
• pyExamples/ folder containing Python example scripts and data
• _static/ folder containing custom CSS, images, test data
b. Configuration & Build Scripts
• conf.py – Sphinx configuration (extensions, themes, paths)
• build.py – custom build orchestration script
• requirements.txt – Python packages needed (Sphinx, extensions)
• .readthedocs.yaml – ReadTheDocs build settings
c. Documentation Generator
• Sphinx “engine” that reads .rst & examples, applies conf.py, and pulls in static assets
d. Output Artifacts
• HTML files (site structure under _build/html/)
• Optional PDF/EPUB builds (via Sphinx builders)
e. Hosting & CI/CD
• Version control (Git/GitHub) storing source & config
• ReadTheDocs (or CI pipeline) that triggers builds on commit and deploys the site
Relationships & Data Flow
• Developers commit source (.rst + examples + static) to GitHub
• .readthedocs.yaml or build.py triggers Sphinx build:
Source Content + conf.py + static assets → Sphinx → Output Artifacts
• Output Artifacts are deployed to ReadTheDocs (or CI/CD server)
• End users browse the hosted HTML docs
Important Architectural Patterns
• Static site generation pattern (Sphinx as build engine)
• Separation of content vs configuration vs build orchestration
• Extensibility points: custom Sphinx extensions, example scripts, static assets
Technologies & Frameworks
• Sphinx (documentation generator)
• reStructuredText (.rst)
• Python 3 (build scripts, examples)
• ReadTheDocs (hosting)
• Git/GitHub (version control)