doc: add minimal docsite

.github/workflows/ci.yml

@@ -89,6 +89,10 @@ jobs:
         timeout-minutes: 10
         uses: ./.github/actions/pdm
 
+      - name: Setup Graphviz
+        timeout-minutes: 10
+        uses: ts-graphviz/setup-graphviz@v2
+
       - name: Install dependencies
         timeout-minutes: 10
         run: pdm install --dev --check --frozen-lockfile
@@ -117,11 +121,41 @@ jobs:
 
       - name: Publish test reports
         timeout-minutes: 10
-        if: always()
+        if: ${{ !cancelled() }}
         uses: pmeier/[email protected]
         with:
           path: tests/.tests.xml
           title: Test results
           summary: true
           display-options: fEX
           fail-on-empty: false
+
+      - name: Setup docs cache
+        timeout-minutes: 10
+        if: ${{ !cancelled() }}
+        uses: actions/cache@v4
+        with:
+          path: docs/build
+          key: docs-cache-${{ hashFiles('docs') }}
+
+      - name: Build docs
+        timeout-minutes: 10
+        if: ${{ !cancelled() }}
+        run: pdm run docs
+
+      - name: Setup Github Pages
+        timeout-minutes: 10
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: actions/configure-pages@v5
+
+      - name: Upload docs to Github Pages
+        timeout-minutes: 10
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/build'
+
+      - name: Deploy GitHub Pages
+        timeout-minutes: 10
+        if: ${{ !cancelled() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        uses: actions/deploy-pages@v4

docs/conf.py

@@ -0,0 +1,80 @@
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from sphinxawesome_theme import ThemeOptions
+from sphinxawesome_theme.postprocess import Icons
+
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+nitpicky = True
+project = "python-erc7730"
+copyright = "2024, Ledger"
+author = "Ledger"
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.githubpages",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.linkcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinxcontrib.mermaid",
+    "sphinxcontrib.typer",
+    "sphinxcontrib.apidoc",
+    "sphinxcontrib.autodoc_pydantic",
+    "myst_parser",
+    "sphinx_github_style",
+    "sphinx_issues",
+    "sphinx_design",
+]
+myst_enable_extensions = [
+    "fieldlist",
+    "linkify",
+    "substitution",
+]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+templates_path = ["templates"]
+issues_github_path = "LedgerHQ/python-erc7730"
+linkcode_url = "LedgerHQ/python-erc7730"
+apidoc_module_dir = "../src"
+apidoc_output_dir = "build/reference"
+apidoc_separate_modules = True
+autosummary_generate = True
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_validator_members = False
+autodoc_pydantic_model_validator_summary = False
+autodoc_pydantic_model_field_summary = False
+autodoc_pydantic_model_hide_paramlist = True
+autodoc_pydantic_model_hide_reused_validator = True
+html_theme = "sphinxawesome_theme"
+html_static_path = ["static"]
+html_css_files = ["custom.css", "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css"]
+html_favicon = "static/ledger-icon.png"
+html_logo = "static/ledger-icon.png"
+html_title = "python-erc7730"
+html_show_sphinx = False
+html_permalinks_icon = Icons.permalinks_icon
+html_context = {"default_mode": "light"}
+html_theme_options = asdict(
+    ThemeOptions(
+        show_prev_next=False,
+        show_scrolltop=True,
+        show_breadcrumbs=True,
+        breadcrumbs_separator=">",
+    )
+)
+pygments_style = "friendly"
+pygments_style_dark = "nord-darker"
+todo_include_todos = True
+mathjax3_config = {"displayAlign": "left"}
+mermaid_version = "11.3.0"

docs/index.md

@@ -0,0 +1,18 @@
+python-erc7730
+==============
+
+**This library provides tooling for the ERC-7730 standard.**
+
+See <https://github.com/LedgerHQ/clear-signing-erc7730-registry> for the standard specification and example descriptors.
+
+This library implements:
+ * Reading and writing ERC-7730 descriptor files into an object model
+ * Validation, available as a command line tool
+ * Conversion between Ledger specific legacy descriptors and ERC-7730
+
+
+```{toctree}
+:maxdepth: 2
+pages/usage_cli.md
+pages/usage_library.md
+```

docs/pages/usage_cli.md

@@ -0,0 +1,53 @@
+# Command line usage
+
+## Installation
+
+The `erc7730` tool is available as a [Python package on PyPI](https://pypi.org/project/erc7730). You can install it
+using `pip`:
+
+```bash
+pip install --user erc7730
+```
+
+## Validation
+
+You can validate your setup by running the `erc7730` command:
+
+```{typer} erc7730.main.app
+:preferred: svg
+:theme: dark
+:width: 100
+:prog: cal
+```
+
+## Commands
+
+### `erc7730 lint`
+
+The `lint` command runs validations on descriptors and outputs warnings and errors to the console:
+```shell
+$ erc7730 lint registry
+checking registry/lido/calldata-stETH.json...
+
+checking registry/lido/calldata-wstETH.json...
+
+checking registry/makerdao/eip712-permit-DAI.json...
+DEBUG: Optional Display field missing: Display field for path `nonce` is missing for message Permit. If intentionally excluded, please add
+it to `exclude` list to avoid this warning.
+WARNING: Missing Display field: Display field for path `owner` is missing for message Permit. If intentionally excluded, please add it to
+`exclude` list to avoid this warning.
+```
+
+It can be called with single files or directories, in which case all descriptors will be checked.
+
+### `erc7730 convert`
+
+The `convert` command converts descriptors between the ERC-7730 format and the legacy formats used by Ledger, for
+instance:
+```shell
+$ erc7730 convert eip712-to-erc7730 ledger-asset-dapps/ethereum/1inch/eip712.json erc7730-eip712-1inch.json
+generated erc7730-eip712-1inch.0x119c71d3bbac22029622cbaec24854d3d32d2828.json ✅
+generated erc7730-eip712-1inch.0x111111125421ca6dc452d289314280a0f8842a65.json ✅
+```
+
+Please run `erc7730 convert --help` for more information on the available options.

docs/pages/usage_library.md

@@ -0,0 +1,120 @@
+# Library usage
+
+## Installation
+
+The `erc7730` library is available as a [Python package on PyPI](https://pypi.org/project/erc7730). You can install it
+using `pip`:
+
+```bash
+pip install --user erc7730
+```
+
+## Overview
+
+A typical usage of the `erc7730` library is to load descriptors and compile them to a wallet manufacturer-specific
+format:
+
+```{mermaid}
+---
+title: Node
+---
+flowchart TD
+   input_json@{ shape: doc, label: "ERC-7730 descriptor file" }
+   input[input ERC-7730 descriptor]
+   resolved[resolved ERC-7730 descriptor]
+   vendor[wallet specific ERC-7730 descriptor]
+   input_json -- load/validate --> input
+   input -- resolve/validate --> resolved
+   resolved -- convert --> vendor
+```
+
+## Packages
+
+### `erc7730.model`
+
+The `erc7730.model` package implements an object model mapping for ERC-7730 descriptors using
+[pydantic](https://docs.pydantic.dev), allowing to easily read/write/transform descriptors.
+
+#### input and resolved forms
+
+Descriptors can be manipulated in 2 forms:
+ - *"Input" form*: the descriptor document as defined in the ERC-7730 specification, after `include` tags have been
+   resolved. It is possible to save back the descriptor back to the original descriptor document. 
+ - *"Resolved" form*: the descriptor after pre-processing:
+    - URLs have been fetched
+    - Contract addresses have been normalized to lowercase
+    - References have been inlined
+    - Constants have been inlined
+    - Field definitions have been inlined
+    - Selectors have been converted to 4 bytes form
+   This form is the most adapted to be used by tools and applications.
+
+```{eval-rst}
+.. autosummary::
+ :nosignatures:
+
+ erc7730.model.input.descriptor.InputERC7730Descriptor
+ erc7730.model.resolved.descriptor.ResolvedERC7730Descriptor
+```
+
+#### input data model
+
+```{eval-rst}
+.. autopydantic_model:: erc7730.model.input.descriptor.InputERC7730Descriptor
+ :noindex:
+ :model-show-config-summary: False
+ :model-show-field-summary: False
+ :model-erdantic-figure: True
+ :model-erdantic-figure-collapsed: False
+```
+
+#### resolved data model
+
+```{eval-rst}
+.. autopydantic_model:: erc7730.model.resolved.descriptor.ResolvedERC7730Descriptor
+ :noindex:
+ :model-show-config-summary: False
+ :model-show-field-summary: False
+ :model-erdantic-figure: True
+ :model-erdantic-figure-collapsed: False
+```
+
+### `erc7730.lint`
+
+The `erc7730.lint` package implements the `erc7730 lint` command. The main interface is `ERC7730Linter`:
+
+```{eval-rst}
+.. autoclass:: erc7730.lint.ERC7730Linter
+ :members:
+```
+
+The package contains several linter implementations:
+
+```{eval-rst}
+.. autosummary::
+ :nosignatures:
+
+ erc7730.lint.lint_validate_abi.ValidateABILinter
+ erc7730.lint.lint_validate_display_fields.ValidateDisplayFieldsLinter
+ erc7730.lint.lint_transaction_type_classifier.ClassifyTransactionTypeLinter
+```
+
+### `erc7730.convert`
+
+The `erc7730.convert` package implements the `erc7730 convert` command. The main interface is `ERC7730Converter`:
+
+```{eval-rst}
+.. autoclass:: erc7730.convert.ERC7730Converter
+ :members:
+```
+
+The package contains several converter implementations:
+
+```{eval-rst}
+.. autosummary::
+ :nosignatures:
+
+ erc7730.convert.convert_erc7730_input_to_resolved.ERC7730InputToResolved
+ erc7730.convert.convert_eip712_to_erc7730.EIP712toERC7730Converter
+ erc7730.convert.convert_erc7730_to_eip712.ERC7730toEIP712Converter
+```

docs/static/custom.css

@@ -0,0 +1,31 @@
+@media (min-width: 1200px) {
+    .container {
+        max-width:1200px
+    }
+}
+
+@media (min-width: 1400px) {
+    .container {
+        max-width:1400px
+    }
+}
+
+@media (min-width: 1600px) {
+    .container {
+        max-width:1600px
+    }
+}
+
+@media (min-width: 1800px) {
+    .container {
+        max-width:1800px
+    }
+}
+
+#content ol, #content ul:not(.search) {
+    margin-top: 0.2rem;
+}
+
+#content ol p, #content ol>li, #content ul:not(.search) p, #content ul:not(.search)>li {
+    margin-top: 0.2rem;
+}