diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..51f1a12 --- /dev/null +++ b/.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/ diff --git a/README.md b/README.md index b60a4d1..373e719 100644 --- a/README.md +++ b/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="" -SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0001", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="" -SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", ATTRS{idProduct}=="0004", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="" +SUBSYSTEMS=="usb", ATTRS{idVendor}=="2c97", MODE="0660", TAG+="uaccess", TAG+="udev-acl" OWNER="" + +KERNEL=="hidraw*", ATTRS{idVendor}=="2c97", MODE="0660" OWNER="" ``` ## 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. diff --git a/VERSIONING.md b/VERSIONING.md deleted file mode 100644 index 78f6e73..0000000 --- a/VERSIONING.md +++ /dev/null @@ -1,15 +0,0 @@ -# Versioning - -The version for this repository is always the same as the version number for the -documentation. In `/doc/source/conf.py`, the `version` option will always be the -latest full version (latest version tag, not including pre-releases) and the -`release` option will be the same, except including pre-releases. As such, they -should always be bumped by the commit that was tagged with a version number. - -The checklist for releasing a new version of this repository (and by extension, -of the documentation) is as follows: - -1. Create a final commit that bumps the version number(s) in - `/doc/source/conf.py` and `/setup.py`. -2. Tag that commit with the appropriate version number. -3. Done! RTD should find the tag and build the docs automagically. diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index b5ffe9d..0000000 --- a/doc/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# BOLOS Python Tools Documentation - -The latest version of this repository can be viewed, pre-built, here: -https://ledger.readthedocs.io/projects/blue-loader-python. - -## Building - -If you wish, you may install Sphinx and build this documentation into a -collection of HTML files yourself. - -Firstly, make sure you have [pip -installed](https://pip.pypa.io/en/stable/installing/). - -Secondly, install Sphinx and the Read the Docs theme: - -``` -pip install sphinx sphinx_rtd_theme -``` - -Finally, build: - -``` -make html -``` - -You will need internet access for intersphinx to work properly. diff --git a/doc/requirements.txt b/doc/requirements.txt deleted file mode 100644 index f54c1f2..0000000 --- a/doc/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -sphinx_argparse diff --git a/doc/source/conf.py b/doc/source/conf.py index 2fe2806..7023e6b 100644 --- a/doc/source/conf.py +++ b/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) -} diff --git a/doc/source/script_reference.rst b/doc/source/script_reference.rst index deb65e4..37b8cbb 100644 --- a/doc/source/script_reference.rst +++ b/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 `, and its `--signApp` flag. .. _updateFirmware.py: diff --git a/pyproject.toml b/pyproject.toml index 2e64c9e..8f05be0 100644 --- a/pyproject.toml +++ b/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"