Improved documentation (#96)

.markdownlint.jsonc

@@ -1,7 +1,15 @@
 {
+
+  // rules https://github.com/DavidAnson/markdownlint
+
   // See https://github.com/DavidAnson/markdownlint-cli2 and
   // https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.jsonc
 
+  // To locally disable a single error, e.g. MD013:
+  // <!-- markdownlint-disable MD013 -->
+  // and after the offending block
+  // <!-- markdownlint-enable MD013 -->
+
   // MD007/ul-indent - Unordered list indentation
   "MD007": {
     // Spaces for indent

HISTORY.md

@@ -2,7 +2,7 @@
 
 Notable changes to the codebase are documented here.
 
-Release names follow [_calendar versioning_](https://calver.org/):
+Release names follow *[calendar versioning](https://calver.org/)*:
 full year, short month, short day (YYYY-M-D)
 
 ## v2023.1.17
@@ -17,7 +17,7 @@ Major changes include:
 - improved typing
 - added SECURITY, CONTRIBUTING, bug report and feature request templates
 - added pre-commit hooks
-- adopted _mypy --strict_ and _from \_\_future\_\_ import annotations_
+- adopted *mypy --strict* and *from \_\_future\_\_ import annotations*
 
 ## v2022.12.31
 

MANIFEST.in

@@ -35,6 +35,7 @@ recursive-include tests *.txt
 recursive-exclude docs/build *
 recursive-include docs *.bat
 recursive-include docs *.py
+recursive-include docs *.md
 recursive-include docs *.rst
 recursive-include docs *.txt
 recursive-include docs Makefile

README.md

@@ -1,14 +1,16 @@
-
 # A Python library for 'bitcoin cryptography'
 
 <!-- markdownlint-disable MD013 -->
 | | |
 | --- | --- |
-| Package | [![python](https://img.shields.io/pypi/pyversions/btclib.svg?logo=python)](https://pypi.python.org/pypi/btclib/) [![calver: yyy.m.d](https://img.shields.io/badge/cal_ver-yyyy.m.d-1674b1.svg?logo=calver)](https://calver.org/) [![pypi](https://img.shields.io/pypi/v/btclib.svg?logo=pypi)](https://pypi.python.org/pypi/btclib/) [![downloads](https://static.pepy.tech/badge/btclib)](https://pepy.tech/project/btclib) [![status](https://img.shields.io/pypi/status/btclib.svg)](https://pypi.python.org/pypi/btclib/) [![license](https://img.shields.io/github/license/btclib-org/btclib.svg)](https://github.com/btclib-org/btclib/blob/master/LICENSE) |
+| Project | [![status](https://img.shields.io/pypi/status/btclib.svg)](https://pypi.python.org/pypi/btclib/) [![license](https://img.shields.io/github/license/btclib-org/btclib.svg)](https://github.com/btclib-org/btclib/blob/master/LICENSE) |
+| Package | [![calver: yyy.m.d](https://img.shields.io/badge/cal_ver-yyyy.m.d-1674b1.svg?logo=calver)](https://calver.org/) [![pypi](https://img.shields.io/pypi/v/btclib.svg?logo=pypi)](https://pypi.python.org/pypi/btclib/) [![downloads](https://static.pepy.tech/badge/btclib)](https://pepy.tech/project/btclib) |
+| Supported platforms | [![python](https://img.shields.io/pypi/pyversions/btclib.svg?logo=python)](https://pypi.python.org/pypi/btclib/) |
 | Formatting standards | [![lint: isort](https://img.shields.io/badge/lint-isort-yellowgreen.svg?logo=isort)](https://github.com/PyCQA/isort) [![lint: black](https://img.shields.io/badge/lint-black-yellowgreen.svg?logo=black)](https://github.com/psf/black) [![lint: flake8](https://img.shields.io/badge/lint-flake8-yellowgreen.svg?logo=flake8)](<https://github.com/PyCQA/flake8>) [![lint: yesqa](https://img.shields.io/badge/lint-yesqa-yellowgreen.svg?logo=yesqa)](<https://github.com/asottile/yesqa>) [![lint: markdownlint-cli2](https://img.shields.io/badge/lint-markdownlint--cli2-yellowgreen.svg?logo=sourcery)](https://github.com/DavidAnson/markdownlint-cli2) |
-| Coding standards | [![type check: mypy](https://img.shields.io/badge/type_check-mypy-yellowgreen.svg?logo=mypy)](http://mypy-lang.org/) [![type check: pyright](https://img.shields.io/badge/type_check-pyright-yellowgreen.svg)](https://github.com/microsoft/pyright) [![lint: pylint](https://img.shields.io/badge/lint-pylint-yellowgreen.svg?logo=pylint)](https://github.com/PyCQA/pylint) [![lint: autoflake](https://img.shields.io/badge/lint-autoflake-yellowgreen.svg?logo=autoflake)](https://github.com/PyCQA/autoflake) [![lint: pyupgrade](https://img.shields.io/badge/lint-pyupgrade-yellowgreen.svg?logo=pyupgrade)](https://github.com/asottile/pyupgrade)  [![lint: sourcery](https://img.shields.io/badge/lint-sourcery-yellowgreen.svg?logo=sourcery)](https://sourcery.ai) [![security: bandit](https://img.shields.io/badge/security-bandit-yellowgreen.svg?logo=bandit)](https://github.com/PyCQA/bandit) |
-| Docs | [![lint: docformatter](https://img.shields.io/badge/lint-docformatter-yellowgreen.svg?logo=docformatter)](https://github.com/PyCQA/docformatter) [![lint: pydocstringformatter](https://img.shields.io/badge/lint-pydocstringformatter-yellowgreen.svg?logo=pydocstringformatter)](https://github.com/DanielNoord/pydocstringformatter) [![lint: pydocstyle](https://img.shields.io/badge/lint-pydocstyle-yellowgreen.svg?logo=pydocstyle)](https://github.com/PyCQA/pydocstyle)|
-| CI/CD | [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/btclib-org/btclib/master.svg)](https://results.pre-commit.ci/latest/github/btclib-org/btclib/master) [![lint](https://github.com/btclib-org/btclib/actions/workflows/lint.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/lint.yml) [![test](https://github.com/btclib-org/btclib/actions/workflows/test.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test.yml) [![test-py312](https://github.com/btclib-org/btclib/actions/workflows/test-pydev.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test-pydev.yml) [![coverage](https://coveralls.io/repos/github/btclib-org/btclib/badge.svg?logo=coveralls)](https://coveralls.io/github/btclib-org/btclib) [![docs](https://img.shields.io/readthedocs/btclib.svg?logo=readthedocs)](https://btclib.readthedocs.io) |
+| Coding standards | [![lint: pylint](https://img.shields.io/badge/lint-pylint-yellowgreen.svg?logo=pylint)](https://github.com/PyCQA/pylint) [![lint: autoflake](https://img.shields.io/badge/lint-autoflake-yellowgreen.svg?logo=autoflake)](https://github.com/PyCQA/autoflake) [![lint: pyupgrade](https://img.shields.io/badge/lint-pyupgrade-yellowgreen.svg?logo=pyupgrade)](https://github.com/asottile/pyupgrade)  [![lint: sourcery](https://img.shields.io/badge/lint-sourcery-yellowgreen.svg?logo=sourcery)](https://sourcery.ai) [![security: bandit](https://img.shields.io/badge/security-bandit-yellowgreen.svg?logo=bandit)](https://github.com/PyCQA/bandit) |
+| Type checking | [![type check: mypy](https://img.shields.io/badge/type_check-mypy-yellowgreen.svg?logo=mypy)](http://mypy-lang.org/) [![type check: pyright](https://img.shields.io/badge/type_check-pyright-yellowgreen.svg)](https://github.com/microsoft/pyright)  |
+| Documentation | [![docs](https://readthedocs.org/projects/btclib/badge/?version=latest)](https://btclib.readthedocs.io) [![lint: docformatter](https://img.shields.io/badge/lint-docformatter-yellowgreen.svg?logo=docformatter)](https://github.com/PyCQA/docformatter) [![lint: pydocstringformatter](https://img.shields.io/badge/lint-pydocstringformatter-yellowgreen.svg?logo=pydocstringformatter)](https://github.com/DanielNoord/pydocstringformatter) [![lint: pydocstyle](https://img.shields.io/badge/lint-pydocstyle-yellowgreen.svg?logo=pydocstyle)](https://github.com/PyCQA/pydocstyle)|
+| CI/CD | [![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit) [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/btclib-org/btclib/master.svg)](https://results.pre-commit.ci/latest/github/btclib-org/btclib/master) [![lint](https://github.com/btclib-org/btclib/actions/workflows/lint.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/lint.yml) [![test](https://github.com/btclib-org/btclib/actions/workflows/test.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test.yml) [![test-py312](https://github.com/btclib-org/btclib/actions/workflows/test-pydev.yml/badge.svg)](https://github.com/btclib-org/btclib/actions/workflows/test-pydev.yml) [![coverage](https://coveralls.io/repos/github/btclib-org/btclib/badge.svg?logo=coveralls)](https://coveralls.io/github/btclib-org/btclib) |
 | Conversations | [![slack](https://img.shields.io/badge/slack-btclib_dev-white.svg?logo=slack)](https://bbt-training.slack.com/messages/C01CCJ85AES) [![Follow on Twitter](https://img.shields.io/twitter/follow/btclib?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=btclib)|
 
 [Browse GitHub Code Repository](https://github.com/btclib-org/btclib/)
@@ -18,22 +20,28 @@
 
 [btclib](https://btclib.org) is a
 Python3 [type annotated](https://docs.python.org/3/library/typing.html)
-library intended for teaching, learning, and using bitcoin,
-its blockchain, and the associated elliptic curve cryptography.
+library intended for teaching, learning, and using bitcoin;
+the focus is on elliptic curve cryptography and bitcoin's blockchain.
 
 It is rigorously and extensively tested: the test suite
 [covers 100%](https://coveralls.io/github/btclib-org/btclib)
 of the code base and reproduces results from both informal
 and major reference sources.
 
 Originally developed for the
-[_Bitcoin and Blockchain Technology_](https://www.ametrano.net/bbt/)
+_[Bitcoin and Blockchain Technology](https://www.ametrano.net/bbt/)_
 course at the University of Milano-Bicocca,
 btclib is not intended for production environments:
 it is often refactored for improved clarity,
 without care for backward compatibility; moreover,
 some of its algorithms could be broken using side-channel attacks.
 
+The library is not limited to the bitcon elliptic curve secp256k1;
+anyway, for this curve FFI bindings to
+[libsecp256k1](https://github.com/bitcoin-core/secp256k1)
+(the optimized C library used by Bitcoin Core)
+are available and used by default.
+
 Included features are:
 
 - modulo algebra functions (gcd, inverse, legendre symbol, square root)
@@ -50,15 +58,15 @@ Included features are:
 - ECDSA signature with (message) compact encoding: standard p2pkh and
   [BIP137](https://github.com/bitcoin/bips/blob/master/bip-0137.mediawiki)/[Electrum](https://electrum.org/#home)
   extensions to p2wpkh and p2wpkh-p2sh
+- [RFC 6979](https://tools.ietf.org/html/rfc6979) for deterministic signature
+  schemes
 - EC Schnorr signature (according to
   [BIP340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
   bitcoin standardization)
     - batch validation
     - threshold signature (see test-suite)
     - MuSig multi-signature (see test-suite)
 - Borromean ring signature
-- [RFC 6979](https://tools.ietf.org/html/rfc6979) to make signature
-  schemes deterministic
 - Sign-to-contract commitment
 - Diffie-Hellman
 - Pedersen committment
@@ -95,7 +103,7 @@ python -m pip install --upgrade btclib
 You might want to install btclib into a
 python virtual environment; e.g. from the root folder:
 
-Shell
+Shell:
 
 ```shell
 python -m venv venv_btclib
@@ -105,7 +113,7 @@ python -m pip install --upgrade btclib
 
 Windows CMD or PowerShell:
 
-```cmd
+```powershell
 python -m venv venv_btclib
 .\venv_btclib\Scripts\activate
 python -m pip install --upgrade btclib

btclib/amount.py

@@ -50,7 +50,21 @@
 
 
 def valid_btc_amount(amount: Any, dust: Decimal = Decimal("0")) -> Decimal:
-    """Return the BTC amount as Decimal, if valid and not less than dust."""
+    """Return the BTC amount as Decimal, if valid and not less than dust.
+
+    Args:
+        amount (Any): The BTC amount. Assumed to be zero if None.
+        dust (Decimal, optional): The minum threshould for a valid amount.
+                                  Defaults to Decimal("0").
+
+    Raises:
+        BTClibValueError: If the amount is below dust or above max
+                          number of bitcoin ever available.
+        BTClibValueError: If the amount has too many (>8) decimals.
+
+    Returns:
+        Decimal: The BTC amount converted to Decimal.
+    """
     # any input that can be converted to str is fine
     amount = "0" if amount is None else str(amount)
     # using str in the Decimal constructor avoids the

btclib/ec/curve_group_2.py

@@ -37,7 +37,7 @@
     - Peter Dettman's field inverses and square roots using a sliding window over blocks of 1s
         -https://briansmith.org/ecc-inversion-addition-chains-01
     - Joint sparse form (JSF) for double mult
-    -  Interleaving with NAFs
+    - Interleaving with NAFs
 """
 
 from __future__ import annotations

docs/Makefile

@@ -1,9 +1,10 @@
 # Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 

docs/README.rst

@@ -19,7 +19,7 @@ Move into the btclib project root folder and autogenerate docs:
 .. sourcecode:: bash
 
     $ cd /path/to/btclibrootfolder
-    $ sphinx-apidoc -f -o ./docs/source ./btclib
+    $ sphinx-apidoc -f -o docs/source btclib/
 
 Perform the above sphinx-apidoc step everytime files are added/removed.
 
@@ -28,7 +28,7 @@ Then, move into the docs directory and build the docs to see how they look:
 .. sourcecode:: bash
 
     $ cd docs
-    $ make html
+    $ make clean html
 
 Your ``index.rst`` has been built into ``index.html``
 in the output subdirectory (``build/html/index.html``).

docs/make.bat

@@ -10,8 +10,6 @@ if "%SPHINXBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 
-if "%1" == "" goto help
-
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
 	echo.
@@ -21,15 +19,17 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 
 :end
 popd

docs/requirements.txt

@@ -1,2 +1,4 @@
-m2r2>=0.3.2
-Sphinx>=4.3.2
+# m2r2
+myst-parser
+sphinx
+sphinx_rtd_theme

docs/source/btclib.ecc.rst

@@ -4,6 +4,14 @@ btclib.ecc package
 Submodules
 ----------
 
+btclib.ecc.bip340\_nonce module
+-------------------------------
+
+.. automodule:: btclib.ecc.bip340_nonce
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 btclib.ecc.bms module
 ---------------------
 
@@ -36,6 +44,14 @@ btclib.ecc.dsa module
    :undoc-members:
    :show-inheritance:
 
+btclib.ecc.libsecp256k1 module
+------------------------------
+
+.. automodule:: btclib.ecc.libsecp256k1
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 btclib.ecc.pedersen module
 --------------------------
 
@@ -44,8 +60,8 @@ btclib.ecc.pedersen module
    :undoc-members:
    :show-inheritance:
 
-btclib.ecc.rfc6979_nonce module
--------------------------
+btclib.ecc.rfc6979\_nonce module
+--------------------------------
 
 .. automodule:: btclib.ecc.rfc6979_nonce
    :members:

docs/source/conf.py

@@ -10,58 +10,52 @@
 
 """Configuration file for the Sphinx documentation builder.
 
-This file only contains a selection of the most common options. For a
-full list see the documentation: www.sphinx-doc.org/en/master/config
+For the full list of built-in configuration values, see the
+documentation: https://www.sphinx-
+doc.org/en/master/usage/configuration.html
 """
 
-# -- Path setup --------------------------------------------------------------
-from __future__ import annotations
-
-import sys
-from os import path
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, path.abspath("../../"))
-
-
 # -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "btclib"
 project_copyright = "2017-2023 The btclib developers"
 author = "The btclib developers"
-
-# The full version, including alpha/beta/rc tags
 release = "2023.1.17"
 
-
 # -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    # "m2r2",
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.coverage",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+]
+
+source_suffix = [".rst", ".md"]
 
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = ["sphinx.ext.autodoc", "m2r2"]
-
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns: list[str] = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 
 # -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
-html_theme = "alabaster"
+html_theme = "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path: list[str] = []
-
-master_doc = "index"
+html_static_path = ["_static"]

docs/source/contributing_link.md

@@ -0,0 +1,6 @@
+<!-- markdownlint-disable MD041 -->
+```{include} ../../CONTRIBUTING.md
+:relative-docs: docs/source/
+:relative-images:
+```
+<!-- markdownlint-enable MD041 -->

docs/source/history_link.md

@@ -0,0 +1,4 @@
+<!-- markdownlint-disable MD041 -->
+```{include} ../../HISTORY.md
+```
+<!-- markdownlint-enable MD041 -->

docs/source/index.rst

@@ -1,16 +1,22 @@
+.. btclib documentation master file.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
 
-.. mdinclude:: ../../README.md
+Welcome to btclib's documentation
+=================================
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   README <readme_link.md>
+   PYTHON PACKAGE <modules>
+   CONTRIBUTING <contributing_link.md>
+   SECURITY <security_link.md>
+   HISTORY <history_link.md>
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
-Contents:
----------
-.. toctree::
-   :maxdepth: 2
-
-   btclib.rst