From 6d7792110d1c24466af63be15d84fe08cb86e443 Mon Sep 17 00:00:00 2001 From: lash Date: Thu, 18 May 2023 06:42:14 +0100 Subject: [PATCH] Package man page with python --- Makefile | 2 - python/CHANGELOG | 3 + python/MANIFEST.in | 2 +- python/Makefile | 8 +- .../man/build/erc20-demurrage-token-publish.1 | 218 ++++++++++++++++++ ...erc20-demurrage-token-publish.custom.groff | 5 + .../erc20-demurrage-token-publish.head.groff | 22 ++ .../erc20-demurrage-token-publish.overrides | 3 + python/setup.cfg | 2 +- python/setup.py | 6 + 10 files changed, 266 insertions(+), 5 deletions(-) create mode 100644 python/man/build/erc20-demurrage-token-publish.1 create mode 100644 python/man/erc20-demurrage-token-publish.custom.groff create mode 100644 python/man/erc20-demurrage-token-publish.head.groff create mode 100644 python/man/erc20-demurrage-token-publish.overrides diff --git a/Makefile b/Makefile index 34b7cd3..1cf7a8b 100644 --- a/Makefile +++ b/Makefile @@ -8,5 +8,3 @@ doc: readme: make -C doc/texinfo readme pandoc -f docbook -t gfm doc/texinfo/build/docbook.xml > README.md - - diff --git a/python/CHANGELOG b/python/CHANGELOG index a3e03ae..4023885 100644 --- a/python/CHANGELOG +++ b/python/CHANGELOG @@ -1,3 +1,6 @@ +- 0.5.3 + * Add texinfo documentation + * Add man page for publish tool - 0.5.2 * Update ERC165 interface response for Expire * Add ExpiryChange event diff --git a/python/MANIFEST.in b/python/MANIFEST.in index 3a5d211..70524d1 100644 --- a/python/MANIFEST.in +++ b/python/MANIFEST.in @@ -1 +1 @@ -include erc20_demurrage_token/data/* erc20_demurrage_token/data/config/*.ini *requirements.txt +include erc20_demurrage_token/data/* erc20_demurrage_token/data/config/*.ini *requirements.txt man/build/*.1 diff --git a/python/Makefile b/python/Makefile index b6fb94c..b3a79ce 100644 --- a/python/Makefile +++ b/python/Makefile @@ -1,2 +1,8 @@ -all: +all: pypi man + +pypi: python setup.py sdist + +man: + mkdir -vp man/build + chainlib-man.py -b 0x3fafff -d man/build -n erc20-demurrage-token-publish -v man diff --git a/python/man/build/erc20-demurrage-token-publish.1 b/python/man/build/erc20-demurrage-token-publish.1 new file mode 100644 index 0000000..61ec054 --- /dev/null +++ b/python/man/build/erc20-demurrage-token-publish.1 @@ -0,0 +1,218 @@ +.TH erc20-demurrage-token-publish 1 + +.SH NAME +erc20-demurrage-token-publish \- Publishing tool for the ERC20 Demurrage Token smart contract. + + +.SH SYNOPSIS +.SY erc20-demurrage-token-publish +.RI --name NAME --symbol SYMBOL --decimals DECIMALS --demurrage-level PPM --redistribution-period MINUTES --sink-address ADDRESS +.YS + + +.SH DESCRIPTION +.P +This tool generates the appropriate bytecode to store the ERC20 Demurrage Token smartcontract code on an EVM chain, along with the required construction parameters. + +Arguments for EVM encoding and interaction with EVM RPC node is handled by the \fBchainlib-eth\fP python package. + +Specific arguments for this tool are the \fB--demurrage-level\fP, \fB--redistribution-period\fP and \fB--sink-address\fP arguments. + + +.SS OPTIONS + +.TP +\fB-0\fP +Omit newline to output + +.TP +\fB-c \fI\fIconfig_dir\fP\fP, \fB--config \fI\fIconfig_dir\fP\fP +Load configuration files from given directory. All files with an .ini extension will be loaded, of which all must contain valid ini file data. + +.TP +\fB--demurrage-level \fI\fIlevel +\fP\fP +Level of decay per minute. See SPECIFYING DEMURRAGE below. + +.TP +\fB--dumpconfig \fI\fIformat\fP\fP +Output configuration settings rendered from environment and inputs. Valid arguments are \fIini\fP for ini file output, and \fIenv\fP for environment variable output. See \fBCONFIGURATION\fP. + +.TP +\fB-e\fP, \fB--executable-address\fP +Address of an executable code point on the network. + +.TP +\fB--env-prefix\fP +Environment prefix for variables to overwrite configuration. Example: If \fB--env-prefix\fP is set to \fBFOO\fP then configuration variable \fBBAR_BAZ\fP would be set by environment variable \fBFOO_BAZ_BAR\fP. Also see \fBENVIRONMENT\fP. + +.TP +\fB--fee-limit\fP +Set the limit of execution units for the transaction. If used with \fB-s\fP this may incur actual network token cost. If \fB--fee-price\fP is not explicitly set, the price \fImay\fP be retrieved from the network, and multiplied with this value to define the cost. + +.TP +\fB--fee-price\fP +Set fee unit price to offer for the transaction. If used with \fB-s\fP this may incur actual network token cost. + +.TP +\fB--height\fP +Block height at which to query state for. Does not apply to transactions. + +.TP +\fB-i \fI\fIchain_spec\fP\fP, \fB--chain-spec \fI\fIchain_spec\fP\fP +Chain specification string, in the format :::. Example: "evm:london:1:ethereum". Overrides the \fIRPC_CREDENTIALS\fP configuration setting. + +.TP +\fB-n \fI\fInamespace\fP\fP, \fB--namespace \fI\fInamespace\fP\fP +Load given configuration namespace. Configuration will be loaded from the immediate configuration subdirectory with the same name. + +.TP +\fB--no-logs\fP +Turn of logging completely. Negates \fB-v\fP and \fB-vv\fP + +.TP +\fB--nonce\fP +Explicitly set nonce to use for transaction. + +.TP +\fB-p\fP, \fB--rpc-provider\fP +Fully-qualified URL of RPC provider. Overrides the \fIRPC_PROVIDER\fP configuration setting. + +.TP +\fB--passphrase-file \fI\fIpath\fP\fP +Path to file containing password to unlock key file + +.TP +\fB--raw\fP +Produce output most optimized for machines. + +.TP +\fB--redistribution-period \fI\fIminutes +\fP\fP +Number of minuntes between each withdrawal of demurraged value is possible. + +.TP +\fB--rpc-auth\fP +RPC endpoint authentication method, e.g. how to handle a HTTP WWW-Authenticate header. Overrides the \fIRPC_AUTH\fP configuration setting. + +.TP +\fB--rpc-credentials\fP +RPC endpoint authentication data. Format depends on the authentication method defined in \fB--rpc-auth\fP. Overrides the \fIRPC_CREDENTIALS\fP configuration setting. + +.TP +\fB--rpc-dialect\fP +RPC backend dialect. If specified it \fImay\fP help with encoding and decoding issues. Overrides the \fIRPC_DIALECT\fP configuration setting. + +.TP +\fB-s\fP +Send to network. If set, network state may change. This means tokens may be spent and so on. Use with care. Only applies to transactions. + +.TP +\fB--seq\fP +Use numeric sequencial jsonrpc query ids. Useful for buggy server implementations who expects such. + +.TP +\fB--sink-address \fI\fIaddress +\fP\fP +Initial address receiving the demurrage value withdrawal. + +.TP +\fB-u\fP, \fB--unsafe\fP +Allow addresses that do not pass checksum. + +.TP +\fB-v\fP +Verbose. Show logs for important state changes. + +.TP +\fB-vv\fP +Very verbose. Show logs with debugging information. + +.TP +\fB-w\fP +Wait for the last transaction to be confirmed on the network. Will generate an error if the EVM execution fails. + +.TP +\fB-ww\fP +Wait for \fIall\fP transactions sequentially to be confirmed on the network. Will generate an error if EVM execution fails for any of the transactions. + +.TP +\fB-y \fI\fIpath\fP\fP, \fB--key-path \fI\fIpath\fP\fP +Path to signing key. Overrides the \fIWALLET_KEY_FILE\fP configuration setting. + +.SH CONFIGURATION + +All configuration settings may be overriden both by environment variables, or by overriding settings with the contents of ini-files in the directory defined by the \fB-c\fP option. + +The active configuration, with values assigned from environment and arguments, can be output using the \fB--dumpconfig\fP \fIformat\fP option. Note that entries having keys prefixed with underscore (e.g. _SEQ) are not actual configuration settings, and thus cannot be overridden with environment variables. + +To refer to a configuration setting by environment variables, the \fIsection\fP and \fIkey\fP are concatenated together with an underscore, and transformed to upper-case. For example, the configuration variable \fIFOO_BAZ_BAR\fP refers to an ini-file entry as follows: + +.EX +[foo] +bar_baz = xyzzy +.EE + +In the \fBENVIRONMENT\fP section below, the relevant configuration settings for this tool is listed along with a short description of its meaning. + +Some configuration settings may also be overriden by command line options. Also note that the use of the \fB-n\fP and \fB--env-prefix\fP options affect how environment and configuration is read. The effects of options on how configuration settings are affective is described in the respective \fBOPTIONS\fP section. + +.SH SPECIFYING DEMURRAGE + +Demurrage is specified as a parts-per-million value in terms of the chosen \fI--redistribution-period\fP. + +For example, a value of \fB20000\fP with a \fI--redistribution-period\fP of \fB43200\fP corresponds to a \fB2%\fP demurrage per \fB30\fP days. +.SH ENVIRONMENT + + +.TP +\fICHAIN_SPEC\fP +String specifying the type of chain connected to, in the format \fI:::\fP. For EVM nodes the \fIengine\fP value will always be \fIevm\fP. + +.TP +\fIRPC_AUTH\fP +Authentication method to use for the \fIRPC_PROVIDER\fP. Currently only \fIbasic\fP is supported. + +.TP +\fIRPC_CREDENTIALS\fP +Authentication credentials to use for \fIRPC_AUTH\fP. For \fIbasic\fP authentication the value must be given as \fI:\fP. + +.TP +\fIRPC_DIALECT\fP +Enables translations of EVM node specific formatting and response codes. + +.TP +\fIRPC_PROVIDER\fP +Fully-qualified URL to the RPC endpoint of the blockchain node. + +.TP +\fIWALLET_KEY_FILE\fP +The wallet key file containing private key to use for transaction signing. Overridden by \fB-y\fP. + +.TP +\fIWALLET_PASSPHRASE\fP +Passphrase to unlock wallet. \fBWARNING:\fP it is \fBunsafe\fP to pass the passphrase as an environment variable. If the key unlocks something of value, the passphrase should rather be in a configuration file, preferably as an encrypted entry. Alternatively, a passphrase can be read from file using the \fB--passphrase-file\fP option. Files containing passphrases should only be accessible by the owner. + +.SH LICENSE + +This documentation and its source is licensed under the Creative Commons Attribution-Sharealike 4.0 International license. + +The source code of the tool this documentation describes is licensed under the GNU General Public License 3.0. + +.SH COPYRIGHT + +Louis Holbrook (https://holbrook.no) +PGP: 59A844A484AC11253D3A3E9DCDCBD24DD1D0E001 + + + +.SH SOURCE CODE + +https://git.defalsify.org + + +.SH SEE ALSO + +.BP +confini-dump(1), eth-keyfile(1) + diff --git a/python/man/erc20-demurrage-token-publish.custom.groff b/python/man/erc20-demurrage-token-publish.custom.groff new file mode 100644 index 0000000..e85b7a8 --- /dev/null +++ b/python/man/erc20-demurrage-token-publish.custom.groff @@ -0,0 +1,5 @@ +.SH SPECIFYING DEMURRAGE + +Demurrage is specified as a parts-per-million value in terms of the chosen \fI--redistribution-period\fP. + +For example, a value of \fB20000\fP with a \fI--redistribution-period\fP of \fB43200\fP corresponds to a \fB2%\fP demurrage per \fB30\fP days. diff --git a/python/man/erc20-demurrage-token-publish.head.groff b/python/man/erc20-demurrage-token-publish.head.groff new file mode 100644 index 0000000..2db9bc0 --- /dev/null +++ b/python/man/erc20-demurrage-token-publish.head.groff @@ -0,0 +1,22 @@ +.TH erc20-demurrage-token-publish 1 + +.SH NAME +erc20-demurrage-token-publish \- Publishing tool for the ERC20 Demurrage Token smart contract. + + +.SH SYNOPSIS +.SY erc20-demurrage-token-publish +.RI --name NAME --symbol SYMBOL --decimals DECIMALS --demurrage-level PPM --redistribution-period MINUTES --sink-address ADDRESS +.YS + + +.SH DESCRIPTION +.P +This tool generates the appropriate bytecode to store the ERC20 Demurrage Token smartcontract code on an EVM chain, along with the required construction parameters. + +Arguments for EVM encoding and interaction with EVM RPC node is handled by the \fBchainlib-eth\fP python package. + +Specific arguments for this tool are the \fB--demurrage-level\fP, \fB--redistribution-period\fP and \fB--sink-address\fP arguments. + + +.SS OPTIONS diff --git a/python/man/erc20-demurrage-token-publish.overrides b/python/man/erc20-demurrage-token-publish.overrides new file mode 100644 index 0000000..6b68b34 --- /dev/null +++ b/python/man/erc20-demurrage-token-publish.overrides @@ -0,0 +1,3 @@ +demurragelevel Level of decay per minute. See SPECIFYING DEMURRAGE below. --demurrage-level level +redistributionperiod Number of minuntes between each withdrawal of demurraged value is possible. --redistribution-period minutes +sinkaddress Initial address receiving the demurrage value withdrawal. --sink-address address diff --git a/python/setup.cfg b/python/setup.cfg index 5ebf562..b3b80f4 100644 --- a/python/setup.cfg +++ b/python/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = erc20-demurrage-token -version = 0.5.2 +version = 0.5.3 description = ERC20 token with redistributed continual demurrage author = Louis Holbrook author_email = dev@holbrook.no diff --git a/python/setup.py b/python/setup.py index 2b8d334..810eb05 100644 --- a/python/setup.py +++ b/python/setup.py @@ -1,4 +1,5 @@ from setuptools import setup +import os requirements = [] f = open('requirements.txt', 'r') @@ -19,6 +20,7 @@ while True: f.close() +man_dir = 'man/build' setup( package_data={ '': [ @@ -28,4 +30,8 @@ setup( include_package_data=True, install_requires=requirements, tests_require=test_requirements, + data_files=[("man/man1", [ + os.path.join(man_dir, 'erc20-demurrage-token-publish.1'), + ] + )], )