Merge pull request #124 from LedgerHQ/doc

Update documentation doc / generation + udev rules in `README.md`

.github/workflows/documentation.yml

@@ -0,0 +1,46 @@
+name: Documentation generation & update
+
+on:
+  push:
+    tags:
+      - '*'
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  generate:
+    name: Generate the documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Install Python dependencies
+        run: |
+          pip install -U pip
+          pip install -U .[doc]
+      - name: Generate the documentation
+        run: (cd doc && make html)
+      - name: Upload documentation bundle
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: doc/build/html/
+
+  deploy:
+    name: Deploy the documentation on Github pages
+    runs-on: ubuntu-latest
+    needs: generate
+    if: github.event_name == 'push'  && (github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/'))
+    steps:
+      - name: Download documentation bundle
+        uses: actions/download-artifact@v3
+      - name: Deploy documentation on pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: documentation/

README.md

@@ -1,4 +1,4 @@
-# Python tools for Ledger Blue, Nano S and Nano X
+# Ledgerblue - Python tools for Ledger Blue, Nano S and Nano X
 
 This package contains Python tools to communicate with Ledger Blue, Nano S and Nano X and manage applications life cycle.
 
@@ -12,7 +12,7 @@ source ledger/bin/activate
 pip install ledgerblue
 ```
 
-## Supported devices 
+## Supported devices
 
 At the moment these tools work for all Nano S, Nano S+, and Blue devices, but only for special Nano X developer units which are not available to the general public.
 The Recover scripts, will work with Nano X starting from a specific version.
@@ -43,9 +43,9 @@ Which would end up installing glibtool and glibtoolize utilities required for th
 When running on Linux, make sure the following rules have been added to `/etc/udev/rules.d/`:
 
 ```
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0000", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="<UNIX username>"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0001", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="<UNIX username>"
-SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0004", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="<UNIX username>"
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="<UNIX username>"
+
+KERNEL=="hidraw*", ATTRS{idVendor}=="2c97", MODE="0660" OWNER="<UNIX username>"
 ```
 
 ## Target ID
@@ -65,3 +65,26 @@ Use the following Target IDs (--targetId option) when running commands directly:
 | `Ledger Blue`    | 2.1.x                              | `0x31000004` |
 | `Ledger Blue v2` | 2.1.x                              | `0x31010004` |
 
+
+## Ledgerblue documentation
+
+You can generate the Ledgerblue documentation locally.
+
+Firstly, make sure you have [pip installed](https://pip.pypa.io/en/stable/installing/) and `make`
+installed.
+
+Then, install the documentation dependencies:
+
+```bash
+# from the top of the Git repository
+pip install .[doc]
+```
+
+Finally, generate the documentation:
+
+```bash
+# from the top of the Git repository
+(cd doc/ && make html)
+```
+
+The documentation will be generated into the `doc/build/` directory.

doc/source/conf.py

@@ -5,10 +5,10 @@
 import os
 import sys
 
-sys.path.append(os.path.abspath('../../'))
+from ledgerblue.__version__ import __version__
 
 def setup(app):
-    app.add_stylesheet('theme_overrides.css') # Override wide tables in RTD theme
+    app.add_css_file('theme_overrides.css') # Override wide tables in RTD theme
 
 # General Configuration
 # =====================
@@ -23,8 +23,8 @@ def setup(app):
 copyright = u'2017, Ledger Team'
 author = u'Ledger Team'
 
-version = u'0.1.30'
-release = u'0.1.30'
+version = __version__
+release = __version__
 
 pygments_style = 'sphinx'
 
@@ -39,12 +39,3 @@ def setup(app):
 # =========
 
 extensions += ['sphinxarg.ext']
-
-# intersphinx
-# ===========
-
-extensions += ['sphinx.ext.intersphinx']
-
-intersphinx_mapping = {
-    'ledger': ('https://ledger.readthedocs.io/en/2/', None)
-}

doc/source/script_reference.rst

@@ -166,10 +166,7 @@ setupCustomCA.py
 signApp.py
 ----------
 
-.. argparse::
-   :module: ledgerblue.signApp
-   :func: get_argparser
-   :prog: python -m ledgerblue.signApp
+See :ref:`loadApp <loadApp.py>`, and its `--signApp` flag.
 
 .. _updateFirmware.py:
 

pyproject.toml

@@ -52,10 +52,15 @@ include-package-data = false
 [project.urls]
 Home = "https://github.com/LedgerHQ/blue-loader-python"
 
-[options.extras_require]
+[project.optional-dependencies]
 smartcard = [
     "python-pyscard>=1.6.12"
 ]
+doc = [
+    "sphinx",
+    "sphinx_rtd_theme",
+    "sphinx_argparse"
+]
 
 [tool.setuptools_scm]
 write_to = "ledgerblue/__version__.py"