commit 89fcf489151a29ed1a2f424f6c34240ebdc6a979
parent 10d481dbb4dc06caab466db8e774aae0771b5383
Author: lash <dev@holbrook.no>
Date: Sun, 13 Nov 2022 09:04:03 +0000
Add build README with templater
Diffstat:
6 files changed, 136 insertions(+), 2 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/Makefile b/Makefile
@@ -12,9 +12,9 @@ doc-prep: prep
prep:
mkdir -p build/out
- #perl setup.pl $(SOURCES) build
readme: prep diagram
+ bash build.sh
diagram:
dot -Tsvg deps.dot > build/deps.svg
diff --git a/README.in b/README.in
@@ -0,0 +1,105 @@
+# Chaintool documentation
+
+Chaintool is still very much a work-in-progress. So too is its documentation.
+
+This README, while still somewhat chaotic, aims to fill the void of a missing structured presentation, and make the introduction to chaintool a bit more friendly.
+
+
+## Showcasing chaintool
+
+The most intuitive entry point to chaintool is most likely the `eth-monitor` tool. It can be installed directly from `pypi` using `pip install eth-monitor`.
+
+<video width="800" height="450" controls>
+ <source src="https://defalsify.org/chaintool_pychain_pitch.mp4">
+Your browser cannot embed this video. Please use the links below instead.
+</video>
+
+Source:
+
+* [video file](https://defalsify.org/chaintool_pychain_pitch.mp4)
+* [video file signatures](https://defalsify.org/chaintool_pychain_pitch.mp4.asc)
+
+## Code components
+
+Upstream souce of chaintool code is located at [git.defalsify.org](https://git.defalsify.org)
+
+
+### Core layer
+
+All libraries that are considered part of the `chaintool` suite:
+
+* **funga**, **funga-eth** - message signing tools and daemon for development, with implementation for EVM.
+* **chainlib**, **chainlib-eth** - blockchain RPC interface with tooling and implementation for EVM nodes.
+* **chainsyncer** - blockchain RPC transaction sync driver.
+* **chainqueue** - blockchain RPC transaction queue control.
+* **eth-cache** - transparent proxy that stores local copies of RPC results.
+
+
+### Higher layer
+
+Tools and daemons building on the core layer.
+
+* **eth-monitor** - Visualization and arbitrary code execution for mined transactions
+* **chaind**, **chaind-eth** - Full-duplex transaction queueing tool for ethereum
+
+
+### Lower layer
+
+Libraries that were developed within the context of `chaintool`, but have a more generic scope.
+
+* **shep** - Multi-state key/value stores using bit masks.
+* **confini** - Parse and merge multiple ini files.
+* **aiee** - Common command line interfacing utils.
+* **leveldir** - Multi-level directory structure data stores.
+* **hexathon** - Common and uncommon hex string operations.
+* **potaahto** - Essentially: Convert between snake and camel case.
+
+The upstream code of these lower layer modules can be found at [holbrook.no/src](https://holbrook.no/src)
+
+
+## Documentation for chaintool
+
+
+So far, documentation efforts have been made in four areas, in order of most recently updated first:
+
+
+### Code components diagram
+
+Last time the author remembered to render it, it looked like this:
+
+<img src="@IMG_URL@" />
+
+The dependency graph is only available in as an unformatted **graphviz** document located at `$REPO_ROOT/deps.dot`. `make diagram` renders this SVG version.
+
+
+### Man pages
+
+The `chainlib` module provides the script `chainlib-man.py` which provides an inheritance approach to generate man pages for CLI tools that build on the library.
+
+An immediate example can be found in the `chainlib-eth` repository, where the directory `$REPO_ROOT/man` demonstrates how to add hooks for overriding both section contents and argument options for individual tools.
+
+What override behavior is currently available should be straightforward to glean from reading the `$CHAINLIB_REPO_ROOT/scripts/chainlib-man.py` script.
+
+Invoking `make man` in the `chainlib-eth` and `eth-monitor` repositories will trigger a build of man pages for all the CLI tools provided.
+
+
+### Descriptive documentation
+
+Some initial work for high-level documentation exists in the chainlib repository, specifically in `$REPO_ROOT/doc/texinfo`.
+
+The documentation can be generated by running `make doc` in the `$REPO_ROOT` of **this** repository. The HTML version of the documentation will be output as a single file to `$REPO_ROOT/build/out/index.html`
+
+
+### Docstrings
+
+Not much to add here. Ye generic sphinx-doc invocation should do the trick.
+
+
+## High-level implementations
+
+To compensate somewhat for the lack of exhaustive documentation, actual implementations using the library may help light the way somewhat.
+
+Aside from the "higher level" components listed above, two known EVM-based implementations that have some minimum level of maturity are:
+
+* [eth-erc20](https://git.defalsify.org/eth-erc20) - an implementation of the ERC20 token, which also includes an example token contract that lets authorized addresses arbitrarily mint tokens at any time.
+* [eth-erc721](https://git.defalsify.org/eth-erc721) - an implementation of the ERC721 "NFT" token, which also includes an example token contract that creates achievment badges for developed contributions.
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@ This README, while still somewhat chaotic, aims to fill the void of a missing st
The most intuitive entry point to chaintool is most likely the `eth-monitor` tool. It can be installed directly from `pypi` using `pip install eth-monitor`.
<video width="800" height="450" controls>
- <source src="https://defalsify.org/chaintool_pychain_pitch.mp4">
+<source src="https://defalsify.org/chaintool_pychain_pitch.mp4">
Your browser cannot embed this video. Please use the links below instead.
</video>
diff --git a/aux/bash-templater b/aux/bash-templater
@@ -0,0 +1,15 @@
+#!/bin/bash
+
+rules="$1"
+source "$rules"
+
+mapfile -t keywords < <(< "$1" sed -n 's/^\([A-Za-z0-9_]\+\)=.*$/\1/p')
+
+while read -r line
+do
+ for keyword in "${keywords[@]}"
+ do
+ line=$(sed "s@\@${keyword}\@@${!keyword}@g" <<<"$line")
+ done
+ echo "$line"
+done < /dev/stdin
diff --git a/build.sh b/build.sh
@@ -0,0 +1,13 @@
+#!/bin/bash
+
+IMG=$(base64 -w 0 build/deps.svg)
+t=$(mktemp )
+cat <<eof > $t
+IMG_URL="data:image/svg+xml;base64,$IMG"
+VIDEO_URL=https://defalsify.org/chaintool_pychain_pitch.mp4
+VIDEO_SIG_URL=https://defalsify.org/chaintool_pychain_pitch.mp4.asc
+eof
+
+>&2 echo building README.md with following vars:
+>&2 cat $t
+bash aux/bash-templater $t < README.in > README.md
