Add UI section to the docs

docs/src/SUMMARY.md

@@ -16,3 +16,14 @@
     - [Audiobookshelf](./audiobookshelf.md)
     - [Search](./search.md)
     - [Full example](./full.md)
+- [UI](./ui/overview.md)
+    - [Home](./ui/home.md)
+    - [Torrents](./ui/torrents.md)
+    - [Events](./ui/events.md)
+    - [Search](./ui/search.md)
+    - [Goodreads lists](./ui/goodreads_lists.md)
+    - [Errors](./ui/errors.md)
+    - [Selected Torrents](./ui/selected.md)
+    - [Replaced Torrents](./ui/replaced.md)
+    - [Duplicate Torrents](./ui/duplicate.md)
+    - [Config](./ui/config.md)

docs/src/ui/config.md

@@ -0,0 +1,14 @@
+# Config
+
+The Config page shows the settings MLM is running with, as read from your configuration file. It is for viewing only. To change a setting, edit the file and restart MLM, as described under [Configuration](../configuration.md).
+
+The page is organised in boxes:
+
+- **General settings** – the settings that apply everywhere, such as the intervals between runs and which file types you prefer.
+- **qBittorrent** – a box for each torrent client. Passwords are hidden.
+- **Autograbbers** – a box for each autograbber, with the search it uses. Its **search on MaM** link opens the same search on MyAnonamouse so you can see what it would find.
+- **Goodreads lists** – a box for each list and the rules for what to grab.
+- **Tags** – rules for tagging torrents in your torrent client. The **apply to all** button applies a rule to all existing torrents in the client you pick. Use it only if you want to tag older torrents too.
+- **Libraries** – where your books are stored, and which torrents go where.
+
+See [Configuration](../configuration.md) for what each setting means.

docs/src/ui/duplicate.md

@@ -0,0 +1,14 @@
+# Duplicate Torrents
+
+When MLM finds a torrent it would normally pick, but you already have that book, it doesn't download it. These skipped torrents are listed here so that you can overrule MLM.
+
+Each entry consists of two rows. The first is the torrent that was skipped. Underneath it, marked **duplicate of:**, is the torrent that you already have. The **Linked** column says whether that one is in your library.
+
+## What you can do
+
+Tick one or more entries to use these buttons:
+
+- **replace original** – use the skipped torrent in place of the one you have.
+- **remove duplicate** – dismiss the entry and keep what you have.
+
+The links at the end of each row open the torrents in MLM, on MyAnonamouse or in Audiobookshelf. If there is nothing to show, the page says *There are currently no duplicate torrents*.

docs/src/ui/errors.md

@@ -0,0 +1,17 @@
+# Errors
+
+When something goes wrong while MLM is downloading, linking or cleaning a torrent, it is listed here, so problems don't go unnoticed.
+
+## The table
+
+- **Step** – where the problem happened (for example grabbing, linking or cleaning).
+- **Title** – the torrent it concerns.
+- **Error** – what went wrong, in the program's own words.
+- **When** – the time it happened.
+- **open** / **MaM** – open the torrent in MLM or on MyAnonamouse, when it is known.
+
+Click **Step** or **Title** values to show only errors of one kind or for one torrent. Click the headings to sort.
+
+## Clearing errors
+
+Tick the errors you have dealt with, then press **remove** to clear them from the list. If you don't see any errors, the page says *There are currently no errors*.

docs/src/ui/events.md

@@ -0,0 +1,18 @@
+# Events
+
+Events is the history of what MLM has done. The newest events are at the top, each with the time it happened.
+
+## Choosing what to show
+
+- **Show** – pick *All*, or narrow it down to one kind of event: *Grabber*, *Linker*, *Cleaner*, *Updated* or *Removed*.
+- **Page size** – how many events are shown per page.
+
+## Kinds of event
+
+- **Grabbed** – MLM selected a torrent for download. It tells you how it was paid for (ratio, freeleech, VIP or a wedge) and which autograbber found it.
+- **Linked** – MLM placed a torrent in your library. It shows the destination folder, and a **Files** section lists the files.
+- **Cleaned** – MLM removed an older version from your library, usually because a preferred format arrived. It shows what was removed and, if there is one, what replaced it.
+- **Updated** – the information about a torrent changed on MyAnonamouse. Each changed field is shown as *old → new*.
+- **Removed from MaM** – the torrent no longer exists on MyAnonamouse.
+
+If nothing has happened yet, the page says *No events yet*.

docs/src/ui/goodreads_lists.md

@@ -0,0 +1,28 @@
+# Goodreads lists
+
+If you have set up [Goodreads lists](../goodreads.md), this page shows them. MLM uses the lists to look for the books you want on MyAnonamouse.
+
+## The lists page
+
+Each list is shown with its name and when it was **Last updated**. Click the name to open it.
+
+Below the active lists, you may see **Inactive Lists**. These were removed from your configuration but are still remembered. MLM no longer refreshes them or searches for their books.
+
+## A single list
+
+A list shows every book on it, with its cover, title, author and series. You can narrow the list down with **Show**:
+
+- **All** – every book,
+- **Any Missing** – books where you are still missing the audiobook or the ebook,
+- **Audio Missing** – books you have no audiobook for,
+- **Ebook Missing** – books you have no ebook for.
+
+For each book MLM tells you what it did:
+
+- *Downloaded* – MLM selected a torrent for it.
+- *Suggest wedge* – a matching torrent was found but is large enough that a wedge is suggested.
+- *Skipped* – MLM skipped it because it found another version, such as an ebook.
+- *Found matching … in library* – you already have it.
+- *Audiobook missing* / *Ebook missing* – nothing suitable has been found yet.
+
+Each book also has a **search on MaM** link, a **goodreads** link and a link to the torrent that was found. If you decide you don't want a missing book after all, press **mark done** and MLM stops looking for it.

docs/src/ui/home.md

@@ -0,0 +1,22 @@
+# Home
+
+The Home page is the control panel for MLM's background jobs. MLM runs these on its own on a schedule. This page shows when each one last ran and lets you start one right away.
+
+At the top you are greeted by name. If something is wrong that stops MLM from working, a red message appears here:
+
+- **mam_id is invalid** – MLM cannot log in to MyAnonamouse, so all features are switched off until you fix the `mam_id` in your configuration.
+- **no qbittorrent instances configured** – MLM has no torrent client to talk to, so all features are switched off.
+
+## The boxes
+
+Each job has its own box showing **Last run** (the time, or "never") and **Result** (*success*, an error message, or *running* while it is busy). Most boxes have a **run now** button.
+
+- **Autograbber** – one box for each autograbber in your configuration. It searches MyAnonamouse for new torrents that match your wishes and selects them for download.
+- **Snatchlist Grabber** – one box for each snatchlist entry in your configuration. It picks up torrents you have already snatched on MyAnonamouse.
+- **Goodreads Import** – one box for each Goodreads list in your configuration. It reads the list and looks for the books on it.
+- **Linker** – places finished downloads in your library folders with tidy names and structure.
+- **Cleaner** – removes older versions from your library when a better one arrives. It has no button, because it runs by itself after the linker.
+- **Torrent downloader** – sends the selected torrents to your torrent client.
+- **Audiobookshelf Matcher** – matches your torrents with the books in Audiobookshelf.
+
+The page updates by itself while it is open, so you can watch a job go from *running* to *success*.

docs/src/ui/overview.md

@@ -0,0 +1,20 @@
+# UI
+
+MLM has a web interface that you open in your browser. Along the top of every page is a row of buttons that take you to the different screens:
+
+**Home**, **Torrents**, **Events**, **Search**, **Goodreads lists**, **Errors**, **Selected Torrents**, **Replaced Torrents**, **Duplicate Torrents** and **Config**.
+
+The following pages describe each screen in that order.
+
+## Things that work the same on most pages
+
+**Tables of torrents.** Several pages show a table with one row per torrent. They share a few habits:
+
+- **Sorting:** click a column heading to sort by it. Click again to reverse the order.
+- **Filtering:** click a value in a row, such as an author, a series or a type, to show only the rows with that value. Hold **Shift** while clicking to add the filter on top of the ones you already have.
+- **Columns:** where there is a *Columns* row of tick boxes, use it to show or hide extra columns.
+- **Page size:** where there is a *Page size* choice, use it to pick how many rows are shown at once. Page links at the bottom let you move between pages.
+- **Selecting rows:** tick the box at the start of a row to select it, or tick the box in the heading to select every row. The action buttons at the top of the page only appear once something is selected.
+- **Links on each row:** **open** shows MLM's own page for the torrent, **MaM** opens it on MyAnonamouse, and **ABS** (if you have set up Audiobookshelf) opens it there.
+
+**Buttons that ask first.** Buttons that remove something show a confirmation question before they do anything.

docs/src/ui/replaced.md

@@ -0,0 +1,15 @@
+# Replaced Torrents
+
+When a better version of a book arrives, for example an m4b audiobook that replaces an mp3 one, MLM takes the old version out of your library. Those old versions are listed here.
+
+Each entry consists of two rows. The first is the old torrent, with the time it was replaced and the time it was added. Underneath it, marked **replaced with:**, is the torrent that took its place.
+
+## What you can do
+
+Use **Columns** to choose which details are shown, and **Page size** to set the number of entries per page. Tick one or more entries to use these buttons:
+
+- **refresh metadata** – fetches the latest information from MyAnonamouse.
+- **refresh metadata and relink** – the same, and then puts the files in the right place in your library.
+- **remove torrent from MLM** – makes MLM forget the torrent.
+
+If there is nothing to show, the page says *You have no replaced torrents*.

docs/src/ui/search.md

@@ -0,0 +1,23 @@
+# Search
+
+Search lets you look for torrents on MyAnonamouse and download them straight from MLM, without leaving the page.
+
+Type what you are looking for in the box and press Enter. Use the cross next to the box to clear it.
+
+## The results
+
+Each result shows:
+
+- the category icon and, next to it, icons for the price (freeleech, VIP or personal freeleech) and for content flags,
+- the title (click it to open MLM's page for the torrent), the authors, series and narrators, plus the file types, audio details and number of comments,
+- the number of files and the size,
+- the date it was added and who uploaded it,
+- the number of seeders, leechers and completed downloads.
+
+Clicking an author, narrator or series name searches for that name. Clicking an uploader's name shows only that person's uploads.
+
+## Downloading
+
+The arrow button in each row selects the torrent for download. After you click it, it turns into a green tick. A green tick that was already there means MLM already has the torrent, or is downloading it.
+
+If you have set a size limit for wedges in your configuration (see [Search](../search.md)), big torrents get a blue arrow instead. That means the torrent will be downloaded using a wedge.

docs/src/ui/selected.md

@@ -0,0 +1,23 @@
+# Selected Torrents
+
+This page shows the torrents that MLM has picked to download, but which have not finished yet. They are waiting in line to be sent to your torrent client, or are being downloaded now.
+
+## The summary
+
+Above the table you can see your MyAnonamouse standing:
+
+- **Buffer** – how much you can download before your ratio becomes a problem,
+- **Unsats** – how many unsatisfied torrents you have, out of the maximum allowed,
+- **Wedges** and **Bonus** – your wedges and bonus points,
+- **Queued Torrents** and **Downloading Torrents** – how many selected torrents are waiting and how many are in progress.
+
+## The table
+
+Choose extra columns with **Columns**. Besides the title and type, you see the **Cost** (how the torrent will be paid for) and **Required Unsats**. The latter is the number of free unsat slots MLM wants to keep before it downloads this torrent.
+
+## Actions
+
+Tick one or more torrents and these buttons appear:
+
+- **unselect for download** – cancels the selection.
+- **set required unsats to** – changes the number in the box next to it for the ticked torrents. A higher number makes MLM wait until more slots are free.

docs/src/ui/torrents.md

@@ -0,0 +1,40 @@
+# Torrents
+
+This page lists every torrent that MLM knows about. That includes torrents it downloaded for you and torrents you added yourself.
+
+## Finding torrents
+
+- **Search** – type in the box and press Enter to filter the list. Click the cross next to the box to clear it.
+- **Columns** – tick the extra columns you want, for example *Authors*, *Narrators*, *Series*, *Language*, *Size*, *Filetypes*, *Path*, *Added At* and *Uploaded At*. The *Flags* column shows small icons for content warnings (such as crude language, violence, explicit content, abridged or LGBT).
+- **Page size** – how many torrents are shown per page.
+- Click any heading to sort, and click a value in a row to filter by it (see the [overview](./overview.md)).
+
+## The table
+
+Each row shows the torrent type, title and whichever other columns you picked. The **Linked** column says whether the torrent has been placed in your library. If you tick **Path**, it shows the actual folder instead.
+
+Some rows carry a small warning sign:
+
+- **⚠ next to a title** – the torrent has been removed from MyAnonamouse but is still being seeded.
+- **ℹ next to a title** – the torrent is not in your torrent client, so it is not seeding.
+- **⚠ next to the link status or path** – the book no longer sits where your current settings say it should, or is no longer wanted in the library. Hover over it to see the details.
+
+At the end of each row are the **open**, **MaM** and **ABS** links.
+
+## Actions
+
+Tick one or more torrents and these buttons appear:
+
+- **refresh metadata** – fetches the latest information about the book from MyAnonamouse.
+- **refresh metadata and relink** – does the same, then moves the files in your library if the new information changes where they belong.
+- **clean torrent** – removes the book from your library folders.
+- **remove torrent from MLM** – makes MLM forget the torrent.
+
+## The torrent page
+
+Clicking **open** on a row shows everything about that one torrent: title, authors, series, narrators, size, files, where it is in your library and its status in your torrent client. From there you can, among other things:
+
+- edit its information by hand with **edit**,
+- stop or start the torrent, and change its category and tags in your torrent client,
+- see the history of what MLM has done with it under **Events**,
+- refresh, relink, clean or remove it, as on the list page.