Skip to content

Commit

Permalink
Merge pull request #515 from LedgerHQ/fix/doc
Browse files Browse the repository at this point in the history
[fix] Moving from Jekyll to Sphinx. RTD theme is safe!
  • Loading branch information
lpascal-ledger authored Sep 9, 2024
2 parents 8c11b57 + 4e44938 commit 2fef8ab
Show file tree
Hide file tree
Showing 18 changed files with 181 additions and 60 deletions.
47 changes: 47 additions & 0 deletions .github/workflows/documentation.yml
Original file line number Diff line number Diff line change
@@ -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/
20 changes: 20 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
7 changes: 0 additions & 7 deletions docs/_config.yml

This file was deleted.

File renamed without changes
File renamed without changes
32 changes: 32 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -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']
5 changes: 0 additions & 5 deletions docs/dev/index.md

This file was deleted.

10 changes: 10 additions & 0 deletions docs/dev/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Developer documentation
=======================

.. toctree::
:maxdepth: 1

getting_started
tests
internals
ci
31 changes: 0 additions & 31 deletions docs/index.md

This file was deleted.

44 changes: 44 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -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>`
5 changes: 0 additions & 5 deletions docs/installation/index.md

This file was deleted.

8 changes: 8 additions & 0 deletions docs/installation/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
Installation
============

.. toctree::
:maxdepth: 1

build
wsl
3 changes: 3 additions & 0 deletions docs/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
sphinx
sphinx-rtd-theme
myst-parser
2 changes: 1 addition & 1 deletion docs/user/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
4 changes: 0 additions & 4 deletions docs/user/docker.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,3 @@
---
sort: 2
---

# Docker

## How to use the Docker image
Expand Down
5 changes: 0 additions & 5 deletions docs/user/index.md

This file was deleted.

14 changes: 14 additions & 0 deletions docs/user/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
User
====

.. toctree::
:maxdepth: 1

api
automation
clients
debug
docker
macm1
semihosting
usage
4 changes: 2 additions & 2 deletions docs/user/macm1.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Docker
# Docker - for Mac M1

## How to build the Docker image

Expand Down Expand Up @@ -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.

0 comments on commit 2fef8ab

Please sign in to comment.