Merge pull request #515 from LedgerHQ/fix/doc

[fix] Moving from Jekyll to Sphinx. RTD theme is safe!

.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/

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)

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']

docs/dev/index.rst

@@ -0,0 +1,10 @@
+Developer documentation
+=======================
+
+.. toctree::
+   :maxdepth: 1
+
+   getting_started
+   tests
+   internals
+   ci

docs/index.rst

@@ -0,0 +1,44 @@
+Speculos documentation
+======================
+
+`Source code <https://github.com/LedgerHQ/speculos>`_
+
+.. toctree::
+   :maxdepth: 1
+
+   installation/index
+   user/index
+   dev/index
+
+
+Users
+-----
+
+Installation and basic usage
+++++++++++++++++++++++++++++
+
+- Linux: :doc:`Requirements and build<installation/build>`
+- Mac OS (and Linux) users: :doc:`How to use the Docker image<user/docker>` with VNC
+- Mac M1 users: :doc:`How to build and use the Docker image<user/macm1>`
+- Windows users: :doc:`Using speculos from WSL 2<installation/wsl>`
+- :doc:`Usage<user/usage>`
+
+Interaction with an app
++++++++++++++++++++++++
+
+- :doc:`How to send APDUs to an app (and more)<user/clients>`
+- :doc:`How to use gdb to debug an app<user/debug>`
+- :doc:`How to automate actions thanks to the REST API<user/api>`
+
+For advanced users
+++++++++++++++++++
+
+- :doc:`Automation: press buttons automatically<user/automation>`
+- :doc:`Semihosting as an additional debug mechanism<user/semihosting>`
+
+Speculos developers
+-------------------
+
+- :doc:`CI (Continuous Integration)<dev/ci>`
+- :doc:`Internals<dev/internals>`
+- :doc:`How to run tests<dev/tests>`

docs/installation/index.rst

@@ -0,0 +1,8 @@
+Installation
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   build
+   wsl

docs/requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx-rtd-theme
+myst-parser

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)

docs/user/docker.md

@@ -1,7 +1,3 @@
----
-sort: 2
----
-
 # Docker
 
 ## How to use the Docker image

docs/user/index.rst

@@ -0,0 +1,14 @@
+User
+====
+
+.. toctree::
+   :maxdepth: 1
+
+   api
+   automation
+   clients
+   debug
+   docker
+   macm1
+   semihosting
+   usage

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.
+Edit `docker-compose.yml` to configure port forwarding and environment variables that fit your needs.