Skip to content

Commit 807ea65

Browse files
jtragliajtraglia
committed
Use mdformat for markdown formatting (#4244)
* Replace skip footnote with html block * Remove unnecessary duration columns * Add mdformat to pyproject * Start to use mdformat-toc * Remove table of contents headers * Fix empty header * Finally, run mdformat * Remove doctoc from CI * Fix issue with eip7732 * Error if linter changes something in CI
1 parent 757e537 commit 807ea65

File tree

96 files changed

+1347
-1802
lines changed

Some content is hidden

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

96 files changed

+1347
-1802
lines changed

‎.github/workflows/run-tests.yml

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,20 +29,15 @@ jobs:
2929
steps:
3030
- name: Checkout repository
3131
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
32-
- name: Setup Node.js
33-
uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e # v4.3.0
34-
with:
35-
node-version: '20'
36-
cache: ''
3732
- name: Setup Python
3833
uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
3934
with:
4035
python-version: '3.12.4'
4136
cache: ''
42-
- name: Install doctoc
43-
run: npm install -g [email protected]
4437
- name: Run linter for pyspec
45-
run: make lint
38+
run: |
39+
make lint
40+
git diff --exit-code
4641
4742
whitespace:
4843
runs-on: [self-hosted-ghr-custom, size-l-x64, profile-consensusSpecs]

‎Makefile

Lines changed: 3 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ VENV = venv
5858
PYTHON_VENV = $(VENV)/bin/python3
5959
PIP_VENV = $(VENV)/bin/pip3
6060
CODESPELL_VENV = $(VENV)/bin/codespell
61+
MDFORMAT_VENV = $(VENV)/bin/mdformat
6162

6263
# Make a virtual environment.
6364
$(VENV):
@@ -185,24 +186,9 @@ MARKDOWN_FILES = $(wildcard $(SPEC_DIR)/*/*.md) \
185186
$(wildcard $(SPEC_DIR)/_features/*/*/*.md) \
186187
$(wildcard $(SSZ_DIR)/*.md)
187188

188-
# Generate ToC sections & save copy of original if modified.
189-
%.toc:
190-
@cp $* $*.tmp; \
191-
doctoc $* > /dev/null; \
192-
if diff -q $* $*.tmp > /dev/null; then \
193-
echo "Good $*"; \
194-
rm $*.tmp; \
195-
else \
196-
echo "\033[1;33m Bad $*\033[0m"; \
197-
echo "\033[1;34m See $*.tmp\033[0m"; \
198-
fi
199-
200-
# Check all files and error if any ToC were modified.
201-
_check_toc: $(MARKDOWN_FILES:=.toc)
202-
@[ "$$(find . -name '*.md.tmp' -print -quit)" ] && exit 1 || exit 0
203-
204189
# Check for mistakes.
205-
lint: pyspec _check_toc
190+
lint: pyspec
191+
@$(MDFORMAT_VENV) --number $(MARKDOWN_FILES)
206192
@$(CODESPELL_VENV) . --skip "./.git,$(VENV),$(PYSPEC_DIR)/.mypy_cache" -I .codespell-whitelist
207193
@$(PYTHON_VENV) -m flake8 --config $(FLAKE8_CONFIG) $(PYSPEC_DIR)/eth2spec
208194
@$(PYTHON_VENV) -m flake8 --config $(FLAKE8_CONFIG) $(TEST_GENERATORS_DIR)

‎docs/docs/new-feature.md

Lines changed: 2 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
11
# How to add a new feature proposal in consensus-specs
22

3-
## Table of contents
4-
5-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
6-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3+
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
74

85
- [A. Make it executable for linter checks](#a-make-it-executable-for-linter-checks)
96
- [1. Create a folder under `./specs/_features`](#1-create-a-folder-under-specs_features)
@@ -22,7 +19,7 @@
2219
- [Bonus](#bonus)
2320
- [Need help?](#need-help)
2421

25-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
22+
<!-- mdformat-toc end -->
2623

2724
## A. Make it executable for linter checks
2825

@@ -38,11 +35,6 @@ For example, if the latest fork is Capella, use `./specs/capella` content as you
3835

3936
- You can either use [Beacon Chain Spec Template](./templates/beacon-chain-template.md), or make a copy of the latest fork content and then edit it.
4037
- Tips:
41-
- We use [`doctoc`](https://www.npmjs.com/package/doctoc) tool to generate the table of content.
42-
```
43-
cd consensus-specs
44-
doctoc specs
45-
```
4638
- The differences between "Constants", "Configurations", and "Presets":
4739
- Constants: The constant that should never be changed.
4840
- Configurations: The settings that we may change for different networks.

‎docs/docs/release.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Release Procedure
22

3-
## Table of contents
4-
5-
<!-- TOC -->
6-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3+
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
84

95
- [Introduction](#introduction)
106
- [Open a Release Pull Request](#open-a-release-pull-request)
@@ -21,8 +17,7 @@
2117
- [Click the Release Buttons](#click-the-release-buttons)
2218
- [Make an Announcement](#make-an-announcement)
2319

24-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
25-
<!-- /TOC -->
20+
<!-- mdformat-toc end -->
2621

2722
## Introduction
2823

‎docs/docs/templates/beacon-chain-template.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,9 @@
22

33
# <FORK_NAME> -- The Beacon Chain
44

5-
## Table of contents
5+
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
66

7-
<!-- TOC -->
8-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
10-
11-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
12-
<!-- /TOC -->
7+
<!-- mdformat-toc end -->
138

149
## Introduction
1510

‎fork_choice/safe-block.md

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
11
# Fork Choice -- Safe Block
22

3-
## Table of contents
4-
5-
<!-- TOC -->
6-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
7-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3+
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
84

95
- [Introduction](#introduction)
106
- [`get_safe_beacon_block_root`](#get_safe_beacon_block_root)
117
- [`get_safe_execution_block_hash`](#get_safe_execution_block_hash)
128

13-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
14-
<!-- /TOC -->
9+
<!-- mdformat-toc end -->
1510

1611
## Introduction
1712

‎pyproject.toml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,10 @@ test = [
3838
lint = [
3939
"codespell==2.4.1",
4040
"flake8==7.2.0",
41+
"mdformat-gfm-alerts==1.0.1",
42+
"mdformat-gfm==0.4.1",
43+
"mdformat-toc==0.3.0",
44+
"mdformat==0.7.22",
4145
"mypy==1.15.0",
4246
"pylint==3.3.6",
4347
]

‎pysetup/constants.py

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,3 @@ def floorlog2(x: int) -> uint64:
3131
def eth_aggregate_pubkeys(pubkeys: Sequence[BLSPubkey]) -> BLSPubkey:
3232
return bls.AggregatePKs(pubkeys)
3333
'''
34-
35-
36-
ETH2_SPEC_COMMENT_PREFIX = "eth2spec:"

‎setup.py

Lines changed: 3 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
from distutils import dir_util
1212
from distutils.util import convert_path
1313
from functools import lru_cache
14-
from marko.block import Heading, FencedCode, LinkRefDef, BlankLine
14+
from marko.block import Heading, FencedCode, HTMLBlock, BlankLine
1515
from marko.ext.gfm import gfm
1616
from marko.ext.gfm.elements import Table
1717
from marko.inline import CodeSpan
@@ -26,7 +26,6 @@
2626

2727
from pysetup.constants import (
2828
PHASE0,
29-
ETH2_SPEC_COMMENT_PREFIX,
3029
)
3130
from pysetup.helpers import (
3231
combine_spec_objects,
@@ -149,17 +148,6 @@ def _load_curdleproofs_crs(preset_name):
149148
}
150149

151150

152-
@lru_cache(maxsize=None)
153-
def _get_eth2_spec_comment(child: LinkRefDef) -> Optional[str]:
154-
title = child.title
155-
if not (title[0] == "(" and title[len(title)-1] == ")"):
156-
return None
157-
title = title[1:len(title)-1]
158-
if not title.startswith(ETH2_SPEC_COMMENT_PREFIX):
159-
return None
160-
return title[len(ETH2_SPEC_COMMENT_PREFIX):].strip()
161-
162-
163151
@lru_cache(maxsize=None)
164152
def _parse_value(name: str, typed_value: str, type_hint: Optional[str] = None) -> VariableDefinition:
165153
comment = None
@@ -324,9 +312,8 @@ def get_spec(file_name: Path, preset: Dict[str, str], config: Dict[str, str], pr
324312
else:
325313
constant_vars[name] = value_def
326314

327-
elif isinstance(child, LinkRefDef):
328-
comment = _get_eth2_spec_comment(child)
329-
if comment == "skip":
315+
elif isinstance(child, HTMLBlock):
316+
if child.body.strip() == "<!-- eth2spec: skip -->":
330317
should_skip = True
331318

332319
# Load KZG trusted setup from files

‎specs/_deprecated/custody_game/beacon-chain.md

Lines changed: 33 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,7 @@
22

33
*Note*: This document is a work-in-progress for researchers and implementers.
44

5-
## Table of contents
6-
7-
<!-- TOC -->
8-
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
9-
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
5+
<!-- mdformat-toc start --slug=github --no-anchors --maxlevel=6 --minlevel=2 -->
106

117
- [Introduction](#introduction)
128
- [Constants](#constants)
@@ -52,8 +48,7 @@
5248
- [Handling of reveal deadlines](#handling-of-reveal-deadlines)
5349
- [Final updates](#final-updates)
5450

55-
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
56-
<!-- /TOC -->
51+
<!-- mdformat-toc end -->
5752

5853
## Introduction
5954

@@ -64,55 +59,55 @@ building upon the [Sharding](../sharding/beacon-chain.md) specification.
6459

6560
### Misc
6661

67-
| Name | Value | Unit |
68-
| - | - | - |
69-
| `CUSTODY_PRIME` | `int(2 ** 256 - 189)` | - |
70-
| `CUSTODY_SECRETS` | `uint64(3)` | - |
71-
| `BYTES_PER_CUSTODY_ATOM` | `uint64(32)` | bytes |
72-
| `CUSTODY_PROBABILITY_EXPONENT` | `uint64(10)` | - |
62+
| Name | Value | Unit |
63+
| ------------------------------ | --------------------- | ----- |
64+
| `CUSTODY_PRIME` | `int(2 ** 256 - 189)` | - |
65+
| `CUSTODY_SECRETS` | `uint64(3)` | - |
66+
| `BYTES_PER_CUSTODY_ATOM` | `uint64(32)` | bytes |
67+
| `CUSTODY_PROBABILITY_EXPONENT` | `uint64(10)` | - |
7368

7469
### Domain types
7570

76-
| Name | Value |
77-
| - | - |
71+
| Name | Value |
72+
| ----------------------------- | -------------------------- |
7873
| `DOMAIN_CUSTODY_BIT_SLASHING` | `DomainType('0x83000000')` |
7974

8075
## Preset
8176

8277
### Time parameters
8378

84-
| Name | Value | Unit | Duration |
85-
| - | - | :-: | :-: |
86-
| `RANDAO_PENALTY_EPOCHS` | `uint64(2**1)` (= 2) | epochs | 12.8 minutes |
87-
| `EARLY_DERIVED_SECRET_PENALTY_MAX_FUTURE_EPOCHS` | `uint64(2**15)` (= 32,768) | epochs | ~146 days |
88-
| `EPOCHS_PER_CUSTODY_PERIOD` | `uint64(2**14)` (= 16,384) | epochs | ~73 days |
89-
| `CUSTODY_PERIOD_TO_RANDAO_PADDING` | `uint64(2**11)` (= 2,048) | epochs | ~9 days |
90-
| `MAX_CHUNK_CHALLENGE_DELAY` | `uint64(2**15)` (= 32,768) | epochs | ~146 days |
79+
| Name | Value | Unit | Duration |
80+
| ------------------------------------------------ | -------------------------- | :----: | :----------: |
81+
| `RANDAO_PENALTY_EPOCHS` | `uint64(2**1)` (= 2) | epochs | 12.8 minutes |
82+
| `EARLY_DERIVED_SECRET_PENALTY_MAX_FUTURE_EPOCHS` | `uint64(2**15)` (= 32,768) | epochs | ~146 days |
83+
| `EPOCHS_PER_CUSTODY_PERIOD` | `uint64(2**14)` (= 16,384) | epochs | ~73 days |
84+
| `CUSTODY_PERIOD_TO_RANDAO_PADDING` | `uint64(2**11)` (= 2,048) | epochs | ~9 days |
85+
| `MAX_CHUNK_CHALLENGE_DELAY` | `uint64(2**15)` (= 32,768) | epochs | ~146 days |
9186

9287
### Max operations per block
9388

94-
| Name | Value |
95-
| - | - |
96-
| `MAX_CUSTODY_CHUNK_CHALLENGE_RECORDS` | `uint64(2**20)` (= 1,048,576) |
97-
| `MAX_CUSTODY_KEY_REVEALS` | `uint64(2**8)` (= 256) |
98-
| `MAX_EARLY_DERIVED_SECRET_REVEALS` | `uint64(2**0)` (= 1) |
99-
| `MAX_CUSTODY_CHUNK_CHALLENGES` | `uint64(2**2)` (= 4) |
100-
| `MAX_CUSTODY_CHUNK_CHALLENGE_RESPONSES` | `uint64(2**4)` (= 16) |
101-
| `MAX_CUSTODY_SLASHINGS` | `uint64(2**0)` (= 1) |
89+
| Name | Value |
90+
| --------------------------------------- | ----------------------------- |
91+
| `MAX_CUSTODY_CHUNK_CHALLENGE_RECORDS` | `uint64(2**20)` (= 1,048,576) |
92+
| `MAX_CUSTODY_KEY_REVEALS` | `uint64(2**8)` (= 256) |
93+
| `MAX_EARLY_DERIVED_SECRET_REVEALS` | `uint64(2**0)` (= 1) |
94+
| `MAX_CUSTODY_CHUNK_CHALLENGES` | `uint64(2**2)` (= 4) |
95+
| `MAX_CUSTODY_CHUNK_CHALLENGE_RESPONSES` | `uint64(2**4)` (= 16) |
96+
| `MAX_CUSTODY_SLASHINGS` | `uint64(2**0)` (= 1) |
10297

10398
### Size parameters
10499

105-
| Name | Value | Unit |
106-
| - | - | - |
107-
| `BYTES_PER_CUSTODY_CHUNK` | `uint64(2**12)` (= 4,096) | bytes |
108-
| `CUSTODY_RESPONSE_DEPTH` | `ceillog2(MAX_SHARD_BLOCK_SIZE // BYTES_PER_CUSTODY_CHUNK)` | - |
100+
| Name | Value | Unit |
101+
| ------------------------- | ----------------------------------------------------------- | ----- |
102+
| `BYTES_PER_CUSTODY_CHUNK` | `uint64(2**12)` (= 4,096) | bytes |
103+
| `CUSTODY_RESPONSE_DEPTH` | `ceillog2(MAX_SHARD_BLOCK_SIZE // BYTES_PER_CUSTODY_CHUNK)` | - |
109104

110105
### Reward and penalty quotients
111106

112-
| Name | Value |
113-
| - | - |
114-
| `EARLY_DERIVED_SECRET_REVEAL_SLOT_REWARD_MULTIPLE` | `uint64(2**1)` (= 2) |
115-
| `MINOR_REWARD_QUOTIENT` | `uint64(2**8)` (= 256) |
107+
| Name | Value |
108+
| -------------------------------------------------- | ---------------------- |
109+
| `EARLY_DERIVED_SECRET_REVEAL_SLOT_REWARD_MULTIPLE` | `uint64(2**1)` (= 2) |
110+
| `MINOR_REWARD_QUOTIENT` | `uint64(2**8)` (= 256) |
116111

117112
## Data structures
118113

0 commit comments

Comments
 (0)