From 4e44938ff818b0a98f6704aa6a38b20dd225033a Mon Sep 17 00:00:00 2001 From: Lucas PASCAL Date: Fri, 6 Sep 2024 12:44:06 +0200 Subject: [PATCH] [fix] Moving from Jekyll to Sphinx. RTD theme is safe! --- .github/workflows/documentation.yml | 47 ++++++++++++++++++ docs/Makefile | 20 ++++++++ docs/_config.yml | 7 --- .../screenshot-api-nanos-btc.png | Bin docs/{ => _static}/screenshot-btc-nanos.png | Bin docs/conf.py | 32 ++++++++++++ docs/dev/index.md | 5 -- docs/dev/index.rst | 10 ++++ docs/index.md | 31 ------------ docs/index.rst | 44 ++++++++++++++++ docs/installation/index.md | 5 -- docs/installation/index.rst | 8 +++ docs/requirements.txt | 3 ++ docs/user/api.md | 2 +- docs/user/docker.md | 4 -- docs/user/index.md | 5 -- docs/user/index.rst | 14 ++++++ docs/user/macm1.md | 4 +- 18 files changed, 181 insertions(+), 60 deletions(-) create mode 100644 .github/workflows/documentation.yml create mode 100644 docs/Makefile delete mode 100644 docs/_config.yml rename docs/{ => _static}/screenshot-api-nanos-btc.png (100%) rename docs/{ => _static}/screenshot-btc-nanos.png (100%) create mode 100644 docs/conf.py delete mode 100644 docs/dev/index.md create mode 100644 docs/dev/index.rst delete mode 100644 docs/index.md create mode 100644 docs/index.rst delete mode 100644 docs/installation/index.md create mode 100644 docs/installation/index.rst create mode 100644 docs/requirements.txt delete mode 100644 docs/user/index.md create mode 100644 docs/user/index.rst diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 00000000..3fd2b50c --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,47 @@ +name: Documentation generation & update + +on: + push: + tags: + - '*' + branches: + - develop + - master + pull_request: + branches: + - develop + - master + +jobs: + generate: + name: Generate the documentation + runs-on: ubuntu-latest + steps: + - name: Clone + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Install Python dependencies + run: | + pip install -r docs/requirements.txt + - name: Generate the documentation + run: (cd docs && make html) + - name: Upload documentation bundle + uses: actions/upload-artifact@v4 + with: + name: documentation + path: docs/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@v4 + - name: Deploy documentation on pages + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: documentation/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..ed880990 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = . +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_config.yml b/docs/_config.yml deleted file mode 100644 index 22c91016..00000000 --- a/docs/_config.yml +++ /dev/null @@ -1,7 +0,0 @@ -title: Speculos documentation -lang: en - -remote_theme: sighingnow/jekyll-gitbook - -exclude: - - screenshot-btc-nanos.png \ No newline at end of file diff --git a/docs/screenshot-api-nanos-btc.png b/docs/_static/screenshot-api-nanos-btc.png similarity index 100% rename from docs/screenshot-api-nanos-btc.png rename to docs/_static/screenshot-api-nanos-btc.png diff --git a/docs/screenshot-btc-nanos.png b/docs/_static/screenshot-btc-nanos.png similarity index 100% rename from docs/screenshot-btc-nanos.png rename to docs/_static/screenshot-btc-nanos.png diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..99111fe7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,32 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Speculos' +copyright = '2024, Ledger' +author = 'Ledger' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ['myst_parser'] + +templates_path = ['_templates'] +exclude_patterns = [] + +source_suffix = { + '.rst': 'restructuredtext', + '.txt': 'markdown', + '.md': 'markdown', +} + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "sphinx_rtd_theme" +html_static_path = ['_static'] diff --git a/docs/dev/index.md b/docs/dev/index.md deleted file mode 100644 index 203a8a49..00000000 --- a/docs/dev/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sort: 3 ---- - -## Developer documentation diff --git a/docs/dev/index.rst b/docs/dev/index.rst new file mode 100644 index 00000000..edc3ac5c --- /dev/null +++ b/docs/dev/index.rst @@ -0,0 +1,10 @@ +Developer documentation +======================= + +.. toctree:: + :maxdepth: 1 + + getting_started + tests + internals + ci diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index fe17154a..00000000 --- a/docs/index.md +++ /dev/null @@ -1,31 +0,0 @@ -# Speculos documentation - -[Source code](https://github.com/LedgerHQ/speculos). - -## Users - -### Installation and basic usage - -- Linux users: [Requirements and build](installation/build.md) -- Mac OS (and Linux) users: [How to use the Docker image](user/docker.md) with VNC -- Mac M1 users: [How to build and use the Docker image](user/macm1.md) -- Windows users: [Using speculos from WSL 2](installation/wsl.md) -- [Usage](user/usage.md) - -### Interaction with an app - -- [How to send APDUs to an app (and more)](user/clients.md) -- [How to use gdb to debug an app](user/debug.md) -- [How to automate actions thanks to the REST API](user/api.md) - -### For advanced users - -- [Automation: press buttons automatically](user/automation.md) -- [Semihosting as an additional debug mechanism](user/semihosting.md) - - -## Speculos developers - -- [CI (Continuous Integration)](dev/ci.md) -- [Internals](dev/internals.md) -- [How to run tests](dev/tests.md) diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..91db3a30 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,44 @@ +Speculos documentation +====================== + +`Source code `_ + +.. toctree:: + :maxdepth: 1 + + installation/index + user/index + dev/index + + +Users +----- + +Installation and basic usage +++++++++++++++++++++++++++++ + +- Linux: :doc:`Requirements and build` +- Mac OS (and Linux) users: :doc:`How to use the Docker image` with VNC +- Mac M1 users: :doc:`How to build and use the Docker image` +- Windows users: :doc:`Using speculos from WSL 2` +- :doc:`Usage` + +Interaction with an app ++++++++++++++++++++++++ + +- :doc:`How to send APDUs to an app (and more)` +- :doc:`How to use gdb to debug an app` +- :doc:`How to automate actions thanks to the REST API` + +For advanced users +++++++++++++++++++ + +- :doc:`Automation: press buttons automatically` +- :doc:`Semihosting as an additional debug mechanism` + +Speculos developers +------------------- + +- :doc:`CI (Continuous Integration)` +- :doc:`Internals` +- :doc:`How to run tests` diff --git a/docs/installation/index.md b/docs/installation/index.md deleted file mode 100644 index 974200c8..00000000 --- a/docs/installation/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sort: 1 ---- - -## Installation diff --git a/docs/installation/index.rst b/docs/installation/index.rst new file mode 100644 index 00000000..61ebd3b8 --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,8 @@ +Installation +============ + +.. toctree:: + :maxdepth: 1 + + build + wsl diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..56c8516d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx +sphinx-rtd-theme +myst-parser diff --git a/docs/user/api.md b/docs/user/api.md index 6f3c52c1..1d0b3947 100644 --- a/docs/user/api.md +++ b/docs/user/api.md @@ -31,4 +31,4 @@ curl -o screenshot.png http://127.0.0.1:5000/screenshot There is a web user interface running directly on [http://127.0.0.1:5000](http://127.0.0.1:5000), which communicates with the API: -![screenshot btc nano s](../screenshot-api-nanos-btc.png) +![screenshot btc nano s](../_static/screenshot-api-nanos-btc.png) diff --git a/docs/user/docker.md b/docs/user/docker.md index 7f1d483a..f5ac5ade 100644 --- a/docs/user/docker.md +++ b/docs/user/docker.md @@ -1,7 +1,3 @@ ---- -sort: 2 ---- - # Docker ## How to use the Docker image diff --git a/docs/user/index.md b/docs/user/index.md deleted file mode 100644 index beead66d..00000000 --- a/docs/user/index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -sort: 2 ---- - -## User diff --git a/docs/user/index.rst b/docs/user/index.rst new file mode 100644 index 00000000..7a5f39f6 --- /dev/null +++ b/docs/user/index.rst @@ -0,0 +1,14 @@ +User +==== + +.. toctree:: + :maxdepth: 1 + + api + automation + clients + debug + docker + macm1 + semihosting + usage diff --git a/docs/user/macm1.md b/docs/user/macm1.md index d2ecfa84..c97fe27d 100644 --- a/docs/user/macm1.md +++ b/docs/user/macm1.md @@ -1,4 +1,4 @@ -# Docker +# Docker - for Mac M1 ## How to build the Docker image @@ -69,4 +69,4 @@ docker-compose up [-d] ``` > Default configuration is nanos / 2.0 / btc.elf / seed "secret" -Edit `docker-compose.yml` to configure port forwarding and environment variables that fit your needs. \ No newline at end of file +Edit `docker-compose.yml` to configure port forwarding and environment variables that fit your needs.