How jupyter/governance works
Project type and purpose
• Type: Static documentation website (governance docs for Project Jupyter)
• Purpose: Maintain Markdown governance documents, build them into a browsable website with Jupyter Book, and publish via GitHub Pages.
File structure
• Top‐level content folders (e.g. charters/, conduct/, elections/, etc.) each containing Markdown source.
• Configuration files: _config.yml (Jupyter Book site config), _toc.yml (table of contents).
• Build scripts/workflows under .github/workflows (build.yml, deploy.yml).
• requirements.txt defines Python dependencies (jupyter-book, etc.).
• README.md explains build instructions; LICENSE.md and governance PDFs/Md files provide content.
README for additional insights
• The site is built locally via jupyter-book build .
• Hosted using GitHub Pages (via a gh-pages branch).
• CI workflows automate build & deploy.
Main components & their interactions
a. Source Repository
• Markdown content + config + CI workflows live in GitHub repo.
b. Continuous Integration (CI)
• GitHub Actions Build workflow: on push to main branch, sets up Python environment, installs Jupyter Book, builds static HTML in _build/html.
c. Continuous Deployment (CD)
• GitHub Actions Deploy workflow: on successful build, pushes static output to gh-pages branch.
d. Static Site Generator
• Jupyter Book CLI transforms .md + config into HTML.
e. Hosting
• GitHub Pages serves content from gh-pages.
f. End Users
• Browsers requesting governance pages at https://jupyter.org/governance.
Architectural patterns / design principles
• Clear separation of concerns:
• Content (Markdown) vs. Presentation (Jupyter Book templates)
• Build logic (CI workflows) vs. hosting (Pages)
• Declarative configuration: _config.yml, _toc.yml, workflows as code
• Static site generation (SSG) pattern
Technologies / frameworks in play
• Jupyter Book (static site generator)
• Python + pip for dependencies
• GitHub Actions for CI/CD
• GitHub Pages for hosting
• Markdown as source content