There is a significant amount of structured reference information in the docs site that lives in markdown tables. To take but one example, see Protocol Parameters.
I propose that structured reference information is stored as json files in a _data/json directory. Tables in documentation can then rendered using python code embedded in the doc pages' .md files by leveraging quarto's executable code blocks capabilities (with echo flag set to false so the py code isn't rendered in the html).
Rationale
substantial reduction in documentation maintenance effort over time
much tighter integration between documentation and source code (using natspec, etc)
reference information has a golden source of truth, following the DRY principle.
Implementation
I haven't considered in detail how this might work, but here's a sketch:
natspecJSON -> tabularJSON -> [html tables]
using solc --devdoc on source code outputs "natspecJSON" objects;
a python script process those and outputs "tabularJSON" files containing reference information (mostly tables); these files live in _data/json inside this repo;
python code inside page markdown source files generates the html tables (using tabulate or other libraries)
There is probably work that needs to get done with the natspec comments in the source code before the full pipleline is viable. But a PoC of the approach could be executed quickly by skipping 1 and writing some of the "tabularJSON" files by hand.
Description
There is a significant amount of structured reference information in the docs site that lives in markdown tables. To take but one example, see Protocol Parameters.
I propose that structured reference information is stored as json files in a
_data/jsondirectory. Tables in documentation can then rendered using python code embedded in the doc pages'.mdfiles by leveraging quarto's executable code blocks capabilities (withechoflag set to false so the py code isn't rendered in the html).Rationale
Implementation
I haven't considered in detail how this might work, but here's a sketch:
solc --devdocon source code outputs "natspecJSON" objects;_data/jsoninside this repo;There is probably work that needs to get done with the natspec comments in the source code before the full pipleline is viable. But a PoC of the approach could be executed quickly by skipping 1 and writing some of the "tabularJSON" files by hand.