diff --git a/Makefile b/Makefile index 2b8df00d7..be82db240 100644 --- a/Makefile +++ b/Makefile @@ -9,7 +9,7 @@ PY_FILES = $(shell find . -type f -name '*.py' | sed 'sO^\./OO' | grep -f ./to C_FILES = $(shell find . -type f -name '*.[ch]' | grep -f ./tools/style.c.include | grep -v -f ./tools/style.c.exclude ) -style_check: pystyle_check ruststyle_check cstyle_check changelog_check yaml_check editor_check ## run all style checks +style_check: pystyle_check ruststyle_check cstyle_check changelog_check yaml_check docs_summary_check editor_check ## run all style checks style: pystyle ruststyle cstyle ## apply all code styles (C+Rust+Py) @@ -138,6 +138,10 @@ ci_docs: ## generate CI documentation ci_docs_check: ## check that generated CI documentation is up to date ./tools/generate_ci_docs.py --check +docs_summary_check: ## check if there are unlinked documentation files + @echo [DOCS-SUMMARY-MARKDOWN-CHECK] + python3 tools/check_docs_summary.py + vendorheader: ## generate vendor header ./core/embed/vendorheader/generate.sh --quiet diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index c6f3ae8f5..9795b1cf8 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -18,6 +18,7 @@ - [SLIP-39](core/misc/slip0039.md) - [Exceptions usage](core/misc/exceptions.md) - [Memory fragmentation management](core/misc/fragmentation.md) + - [DISC1](core/misc/disc1.md) - [Legacy](legacy/index.md) - [Firmware format](legacy/firmware-format.md) - [Python](python/index.md) diff --git a/docs/python/show-text-01.png b/docs/python/show-text-01.png deleted file mode 100644 index cc7b7c10e..000000000 Binary files a/docs/python/show-text-01.png and /dev/null differ diff --git a/docs/python/show-text-02.png b/docs/python/show-text-02.png deleted file mode 100644 index cce2e128b..000000000 Binary files a/docs/python/show-text-02.png and /dev/null differ diff --git a/docs/python/show-text-03.png b/docs/python/show-text-03.png deleted file mode 100644 index f622b0d5c..000000000 Binary files a/docs/python/show-text-03.png and /dev/null differ diff --git a/docs/python/show-text-04.png b/docs/python/show-text-04.png deleted file mode 100644 index 0eeb3f1ec..000000000 Binary files a/docs/python/show-text-04.png and /dev/null differ diff --git a/docs/python/show-text-05.png b/docs/python/show-text-05.png deleted file mode 100644 index 8c3db1b86..000000000 Binary files a/docs/python/show-text-05.png and /dev/null differ diff --git a/docs/python/show-text-06.png b/docs/python/show-text-06.png deleted file mode 100644 index ba4d98113..000000000 Binary files a/docs/python/show-text-06.png and /dev/null differ diff --git a/docs/python/show-text-07.png b/docs/python/show-text-07.png deleted file mode 100644 index f91a4588f..000000000 Binary files a/docs/python/show-text-07.png and /dev/null differ diff --git a/docs/python/show-text.md b/docs/python/show-text.md deleted file mode 100644 index d127f8257..000000000 --- a/docs/python/show-text.md +++ /dev/null @@ -1,137 +0,0 @@ -# Displaying text screens on Trezor T - -## Requirements - -For this feature, you will need a debug-enabled firmware for Trezor T. Usually that -will be the emulator. - -You will also need `trezorctl` 0.12 or later. Best bet is to run the version from github -master. - -## Trezor T text capabilities - -The Trezor T screen has a _header_, with an icon and text. Below it is _body_, which -can fit up to 5 lines of text. - -Text can be in one of several colors, and in one of three styles: NORMAL, BOLD, MONO. - -It is possible to have multiple styles on the same line, but different styles must be -separated by a space. - -I.e., this works fine: - -> This word is **bold** and this is `monospaced`. - -This will not work: - -> Em**bold**ened middle, mono`space`d middle. - -A line that is too long to fit on screen will automatically break, using a hyphen (`-`) -character. This is usually undesirable. Instead, a manual line-break should be inserted -in the appropriate place. - -## Command line syntax - -The most basic way to put words on screen is this: - -```sh -trezorctl debug show-text "My hovercraft is full of eels, call the porter, there is a frog in my bidet." -``` - -The above command will show: - -![Screenshot01](show-text-01.png) - -Notice the "quotes" around the text. The whole body text must be enquoted. - -To use quotes inside the text, prefix them with backslashes `\`: - -```sh -trezorctl debug show-text "My \"hovercraft\" is full of eels." -``` - -![Screenshot02](show-text-02.png) - -### Line breaks - -Let's insert some line breaks. Do that by placing `@@BR` in the appropriate place -in the text: - -```sh -trezorctl debug show-text "My hovercraft is full of @@BR eels, call the porter, @@BR there is a frog in my @@BR bidet." -``` - -![Screenshot03](show-text-03.png) - -Better! - -### Text styles - -Now let's add some style. Use `@@BOLD` to start printing in bold. Use `@@NORMAL` -to go back to normal text. `@@MONO` works similarly. - -```sh -trezorctl debug show-text "My hovercraft is @@BOLD full of @@BR eels. @@NORMAL Call the porter, @@BR there is a @@MONO frog @@NORMAL in my @@BR bidet." -``` - -![Screenshot04](show-text-04.png) - -### Line spacing - -Adding another `@@BR` after a `@@BR` will leave one line empty -- just like pressing -\ twice. - -If you don't want a full empty line, you can make a half-break with `@@BR_HALF`. - -```sh -trezorctl debug show-text "Line one. @@BR @@BR Line two. @@BR @@BR_HALF Line three." -``` - -![Screenshot05](show-text-05.png) - - -### Text colors - -To switch to one of the [available colors](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L15-L44), -use the color name prefixed with `%%`: e.g., `%%RED`, `%%LIGHT_BLUE`... - -To switch back to the default color, you can use `%%FG`: - -```sh -trezorctl debug show-text "My %%RED hovercraft is @@BOLD full %%GREEN of @@BR eels. @@NORMAL Call %%ORANGE the %%FG porter." -``` - -![Screenshot06](show-text-06.png) - -### Headers - -The default header says "Showing text" with an orange gear icon. It is possible to -change all of that. - -To change the text, use `-h` option: - -```sh -trezorctl debug show-text -h "Hello world" "My hovercraft is full." -``` - -To change the icon, you can pick [an icon name from here](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L51-L71) and specify it with the `-i` option: - -```sh -trezorctl debug show-text -i RECEIVE "My hovercraft is full." -``` - -The icons are defined as shapes, and you can specify a custom color [from the list](https://github.com/trezor/trezor-firmware/blob/master/core/src/trezor/ui/style.py#L15-L44) with the `-c` option: - -```sh -trezorctl debug show-text -c RED "My hovercraft is full." -``` - -### Putting it all together - -Here is how to reproduce the confirmation screen after the wallet is created: - -```sh -trezorctl debug show-text -h "Success" -i CONFIRM -c GREEN "@@BOLD New wallet created @@BR successfully! @@BR @@BR_HALF @@NORMAL You should back up your @@BR new wallet right now." -``` - -![Screenshot07](show-text-07.png) diff --git a/docs/storage/addon-block.md b/docs/storage/addon-block.md deleted file mode 100644 index 4e88bde59..000000000 --- a/docs/storage/addon-block.md +++ /dev/null @@ -1,40 +0,0 @@ -# Add-on Block - -Fixed storage which stores an immutable binary-search tree of items. -Each item consists of a pair of pointers to binary data of arbitrary length. -These two pointers are interpreted as a `key` and a `value`. -Since items contain only pointers, multiple instances of data are stored just once. - -Block contains 3 logical parts: -a) header (256 bytes) -b) binary-search tree (variable size) -c) item data (variable size) - -## Header - -| offset | length | name | description | -|-------:|---------:|--------------|--------------| -| 0x0000 | 4 | magic | magic `TRAB` | -| 0x0004 | 64 | sig | signature of the whole blob (except magic and sig) | -| 0x0044 | 4 | tree_count | number of elements in the tree | -| 0x0048 | 4 | items_size | length of the item section | -| 0x004A | 182 | reserved | - | - -## Binary-Search Tree - -Each node of the tree has the following structure: - -| offset | length | name | description | -|-------:|---------:|--------------|--------------| -| ... | 2 | key_offset | key offset (divided by 4) | -| ... | 2 | value_offset | value offset (divided by 4) | - -# Item Data - -Each item has the following structure: - -| offset | length | name | description | -|-------:|---------:|--------------|--------------| -| ... | 2 | item_len | item (key or value) length | -| ... | 2 | item_flags | item (key or value) flags | -| ... | item_len | item_data | item (key or value) data (padded to multiple of 4) | diff --git a/tools/check_docs_summary.py b/tools/check_docs_summary.py new file mode 100755 index 000000000..30c68fe21 --- /dev/null +++ b/tools/check_docs_summary.py @@ -0,0 +1,82 @@ +""" +This script lists names of markdown files (.md extenstion) present in docs/ directory +which are not referenced in SUMMARY.md file which serves as a firmware docu mainpage. + +Running the script: +- `python tools/check_docs_summary.py` from trezor-firmware root directory. +""" + +import re +import sys +from pathlib import Path +from typing import Generator, Iterable, Set + +DOCS_DIR = "docs/" +SUMMARY_FILENAME = "SUMMARY.md" +RE_MARKDOWN_LINK = r"\[.*?\]\((.+.md)\)" + + +def gen_pat_in_file( + filepath: str, pat: re.Pattern, grp_idx: int +) -> Generator[str, None, None]: + with open(filepath, "r", encoding="utf-8") as f: + for line in f.readlines(): + match = re.search(pat, line) + if match: + yield match.group(grp_idx) + + +def gen_convert_to_str(inputs: Iterable[Path]) -> Generator[str, None, None]: + for i in inputs: + yield str(i) + + +def gen_ltrim_pat(inputs: Iterable[str], pat: str) -> Generator[str, None, None]: + for i in inputs: + if i.startswith(pat): + yield i[len(pat) :] + + +def gen_skip(inputs: Iterable[str], what: str) -> Generator[str, None, None]: + for i in inputs: + if i != what: + yield i + + +def difference(g1: Iterable[str], g2: Iterable[str]) -> Generator[str, None, None]: + set_g2: Set[str] = set(g2) + for item in g1: + if item not in set_g2: + yield item + + +def print_result(filenames: Iterable[str]) -> None: + if not filenames: + print("OK") + sys.exit(0) + else: + print( + f"ERROR: these files exist in {DOCS_DIR} but are not linked in {DOCS_DIR + SUMMARY_FILENAME}" + ) + for f in filenames: + print(f"\t- {f}") + sys.exit(1) + + +def main(): + re_md_link = re.compile(RE_MARKDOWN_LINK) + + md_files_in_docs_dir = Path(DOCS_DIR).rglob("*.md") + md_files_in_docs_dir = gen_convert_to_str(md_files_in_docs_dir) + md_files_in_docs_dir = gen_ltrim_pat(md_files_in_docs_dir, DOCS_DIR) + md_files_in_docs_dir = gen_skip(md_files_in_docs_dir, SUMMARY_FILENAME) + + md_files_linked_in_summary = gen_pat_in_file( + DOCS_DIR + SUMMARY_FILENAME, re_md_link, 1 + ) + diff = difference(md_files_in_docs_dir, md_files_linked_in_summary) + print_result(list(diff)) + + +if __name__ == "__main__": + main()