Skip to content

Commit a70e21f

Browse files
BenSchZABenSchZA
authored
Add Jupyter Book documentation and CI pipeline (#146)
* Add Jupyter Book documentation and CI pipeline * Fix Jupyter Book package conflict * Update code documentation * Update code documentation * Update CADLabs logo * Update GitHub action to only execute on main branch
1 parent 32605e5 commit a70e21f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+271
-10447
lines changed

‎.github/workflows/jupyter-book.yml

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
name: deploy-book
2+
3+
# Run this when the master or main branch changes
4+
on:
5+
branchs: [ main ]
6+
# push:
7+
# branches: [ main ]
8+
# pull_request:
9+
# branches: [ main ]
10+
# If your git repository has the Jupyter Book within some-subfolder next to
11+
# unrelated files, you can make this run only if a file within that specific
12+
# folder has been modified.
13+
#
14+
# paths:
15+
# - some-subfolder/**
16+
17+
# This job installs dependencies, builds the book, and pushes it to `gh-pages`
18+
jobs:
19+
deploy-book:
20+
runs-on: ubuntu-latest
21+
permissions:
22+
pages: write
23+
id-token: write
24+
steps:
25+
- uses: actions/checkout@v3
26+
27+
# Install dependencies
28+
- name: Set up Python 3.9
29+
uses: actions/setup-python@v4
30+
with:
31+
python-version: 3.9
32+
33+
- name: Install dependencies
34+
run: |
35+
pip install -r requirements.txt
36+
37+
# (optional) Cache your executed notebooks between runs
38+
# if you have config:
39+
# execute:
40+
# execute_notebooks: cache
41+
- name: Cache executed notebooks
42+
uses: actions/cache@v3
43+
with:
44+
path: docs/_build/.jupyter_cache
45+
key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
46+
47+
# Build the book
48+
- name: Build the book
49+
run: |
50+
make build-docs
51+
52+
# Upload the book's HTML as an artifact
53+
- name: Upload artifact
54+
uses: actions/upload-pages-artifact@v2
55+
with:
56+
path: "docs/_build/html"
57+
58+
# Deploy the book's HTML to GitHub Pages
59+
- name: Deploy to GitHub Pages
60+
id: deployment
61+
uses: actions/deploy-pages@v2

‎.gitignore

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -106,13 +106,13 @@ celerybeat.pid
106106
*.sage.py
107107

108108
# Environments
109-
.env
110-
.venv
111-
env/
112-
venv/
113-
ENV/
114-
env.bak/
115-
venv.bak/
109+
.env*
110+
.venv*
111+
env*/
112+
venv*/
113+
ENV*/
114+
env*.bak/
115+
venv*.bak/
116116

117117
# Spyder project settings
118118
.spyderproject
@@ -142,6 +142,7 @@ scratchpad/
142142
*.nbconvert.ipynb
143143
*.dat
144144
drafts/
145+
_autosummary/
145146

146147
# Masterclass exam
147148
**/*answers.ipynb

‎Makefile

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,14 @@ test: execute-notebooks
2020
# Run Pytest tests
2121
python3 -m pytest -m "not api_test" tests
2222

23-
build-docs: docs-pdoc docs-jupyter-book
23+
build-docs: docs-jupyter-book
2424

2525
docs-pdoc:
2626
pdoc --html model -o docs --force
2727

2828
docs-jupyter-book:
2929
jupyter-book clean docs
30-
jupyter-book build --config docs/_config.yml --toc docs/_toc.yml --path-output docs .
31-
cp -r ./docs/model ./docs/_build/html/docs/model
30+
python build_docs.py
3231

3332
serve-docs:
3433
gunicorn -w 4 -b 127.0.0.1:5000 docs.server:app

‎build_docs.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
from jupyter_book.cli.main import main
2+
3+
# See https://stackoverflow.com/questions/74367920/sphinx-recursive-autosummary-not-importing-modules
4+
# jupyter-book build --config docs/_config.yml --toc docs/_toc.yml --path-output docs .
5+
main(["build", "--config", "docs/_config.yml", "--toc", "docs/_toc.yml", "--path-output", "docs", "."])

‎docs/_config.yml

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,27 @@
1-
title: "CADLabs Ethereum Research Model Documentation"
2-
# logo: media/_.png
1+
title: "CADLabs Ethereum Economic Model"
2+
logo: docs/logo.png
33
only_build_toc_files: true
44
execute:
5-
execute_notebooks: "off"
5+
# execute_notebooks: off
6+
execute_notebooks: cache
7+
parse:
8+
myst_enable_extensions:
9+
# don't forget to list any other extensions you want enabled,
10+
# including those that are enabled by default!
11+
- amsmath
12+
- dollarmath
13+
- html_image
14+
- attrs_inline
615
sphinx:
16+
extra_extensions:
17+
- 'sphinx.ext.autodoc'
18+
- 'sphinx.ext.autosummary'
19+
- 'sphinx.ext.napoleon'
20+
- 'sphinx.ext.viewcode'
721
config:
22+
# html_theme: pydata_sphinx_theme
23+
templates_path: ['docs/_templates/autosummary']
24+
add_module_names: True
25+
autosummary_generate: True
826
html_js_files:
9-
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js
27+
- https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js

‎docs/_templates/autosummary/custom-class-templates.rst

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ objname }}
6+
:members:
7+
:show-inheritance:
8+
:inherited-members:
9+
10+
{% block methods %}
11+
.. automethod:: __init__
12+
13+
{% if methods %}
14+
.. rubric:: {{ _('Methods') }}
15+
16+
.. autosummary::
17+
{% for item in methods %}
18+
~{{ name }}.{{ item }}
19+
{%- endfor %}
20+
{% endif %}
21+
{% endblock %}
22+
23+
{% block attributes %}
24+
{% if attributes %}
25+
.. rubric:: {{ _('Attributes') }}
26+
27+
.. autosummary::
28+
{% for item in attributes %}
29+
~{{ name }}.{{ item }}
30+
{%- endfor %}
31+
{% endif %}
32+
{% endblock %}

‎docs/_templates/autosummary/custom-module-template.rst

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. automodule:: {{ fullname }}
4+
5+
{% block attributes %}
6+
{% if attributes %}
7+
.. rubric:: Module Attributes
8+
9+
.. autosummary::
10+
:toctree:
11+
{% for item in attributes %}
12+
{{ item }}
13+
{%- endfor %}
14+
{% endif %}
15+
{% endblock %}
16+
17+
{% block functions %}
18+
{% if functions %}
19+
.. rubric:: {{ _('Functions') }}
20+
21+
.. autosummary::
22+
:toctree:
23+
{% for item in functions %}
24+
{{ item }}
25+
{%- endfor %}
26+
{% endif %}
27+
{% endblock %}
28+
29+
{% block classes %}
30+
{% if classes %}
31+
.. rubric:: {{ _('Classes') }}
32+
33+
.. autosummary::
34+
:toctree:
35+
:template: custom-class-template.rst
36+
{% for item in classes %}
37+
{{ item }}
38+
{%- endfor %}
39+
{% endif %}
40+
{% endblock %}
41+
42+
{% block exceptions %}
43+
{% if exceptions %}
44+
.. rubric:: {{ _('Exceptions') }}
45+
46+
.. autosummary::
47+
:toctree:
48+
{% for item in exceptions %}
49+
{{ item }}
50+
{%- endfor %}
51+
{% endif %}
52+
{% endblock %}
53+
54+
{% block modules %}
55+
{% if modules %}
56+
.. rubric:: Modules
57+
58+
.. autosummary::
59+
:toctree:
60+
:template: custom-module-template.rst
61+
:recursive:
62+
{% for item in modules %}
63+
{{ item }}
64+
{%- endfor %}
65+
{% endif %}
66+
{% endblock %}

‎docs/_toc.yml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,19 @@
11
format: jb-book
2-
root: docs/landing-page
2+
root: README
33
parts:
4+
- caption: Model Overview
5+
chapters:
6+
# - file: README
7+
# title: "Model README"
8+
- file: ASSUMPTIONS
9+
- file: ROADMAP
10+
- file: CHANGELOG
411
- caption: Model Specification
512
chapters:
613
- file: docs/model_specification/mathematical_specification
714
- caption: Documentation
815
chapters:
9-
- url: https://cadlabs.gitlab.io/cadlabs-ethereum-model-docs/docs/index.html
10-
title: Model Code Documentation
16+
- file: docs/code.rst
1117
- caption: Experiment Notebooks
1218
chapters:
1319
- file: experiments/notebooks/0_README

‎docs/code.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Model Code Documentation
2+
=================
3+
4+
.. autosummary::
5+
:toctree: _autosummary
6+
:recursive:
7+
8+
model.parts
9+
model.constants
10+
model.state_update_blocks
11+
model.state_variables
12+
model.stochastic_processes
13+
model.system_parameters
14+
model.types
15+
model.utils

‎docs/introduction.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Introduction
2+
3+
A modular dynamical-systems model of Ethereum's validator economics, based on the open-source Python library [radCAD](https://github.com/CADLabs/radCAD), an extension to [cadCAD](https://cadcad.org).
4+
5+
This open-source model was developed in collaboration with the Ethereum Robust Incentives Group and funded by an Ethereum ESP (Ecosystem Support Program) grant. While originally scoped with purely modelling-educational intent as part of the cadCAD Edu online course "[cadCAD Masterclass: Ethereum Validator Economics](https://www.cadcad.education/course/masterclass-ethereum)", it has evolved to become a highly versatile, customizable and extensible research model that includes a list of [model extension ideas](#Model-Extension-Roadmap). The model is focused on epoch- and population-level Ethereum validator economics across different deployment types and – at least in its initial setup – abstracts from slot- and agent-level dynamics. Please see [Model Assumptions](ASSUMPTIONS.md) for further context.
6+
7+
* GitHub repo: [CADLabs Ethereum Economic Model](https://github.com/CADLabs/ethereum-economic-model)
8+
* Latest model release version: [Subgraph / v1.1.7](https://github.com/CADLabs/ethereum-economic-model/releases/tag/v1.1.7)
9+
* Implements the official Ethereum [Altair](https://github.com/ethereum/eth2.0-specs#altair) spec updates in the [Blue Loop / v1.1.0-alpha.7](https://github.com/ethereum/eth2.0-specs/releases/tag/v1.1.0-alpha.7) release
10+
11+
## Model Features
12+
13+
* Configurable to reflect protocol behaviour at different points in time of the development roadmap (referred to as "upgrade stages"):
14+
* Post Beacon Chain launch, pre EIP-1559, pre PoS (validators receive PoS incentives, EIP-1559 disabled, and PoW still in operation)
15+
* Post Beacon Chain launch, post EIP-1559, pre PoS (validators receive PoS incentives, EIP-1559 enabled with miners receiving priority fees, and PoW still in operation)
16+
* Post Beacon Chain launch, post EIP-1559, post PoS (validators receive PoS incentives, EIP-1559 enabled with validators receiving priority fees, and PoW deprecated)
17+
* Flexible calculation granularity: By default, State Variables, System Metrics, and System Parameters are calculated at epoch level and aggregated daily (~= 225 epochs). Users can easily change epoch aggregation using the delta-time (`dt`) parameter. The model can be extended for slot-level granularity and analysis if that is desired (see [Model Extension Roadmap](#Model-Extension-Roadmap)).
18+
* Supports [state-space analysis](https://en.wikipedia.org/wiki/State-space_representation) (i.e. simulation of system state over time) and [phase-space analysis](https://en.wikipedia.org/wiki/Phase_space) (i.e. generation of all unique system states in a given experimental setup).
19+
* Customizable processes to set important variables such as ETH price, ETH staked, and EIP-1559 transaction pricing.
20+
* Modular model structure for convenient extension and modification. This allows different user groups to refactor the model for different purposes, rapidly test new incentive mechanisms, or update the model as Ethereum implements new protocol improvements.
21+
* References to official [Eth2 specs](https://github.com/ethereum/eth2.0-specs) in Policy and State Update Function logic. This enables seamless onboarding of protocol developers and allows the more advanced cadCAD user to dig into the underlying protocol design that inspired the logic.

0 commit comments

Comments
 (0)