docs: impl tool to list .md missing in SUMMARY.md

[no changelog]

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
 

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)

docs/python/show-text.md

@@ -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
-\<Enter\> 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)

docs/storage/addon-block.md

@@ -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) |

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()