chore: update the documentation

Author: cuinixam

docs/features/logging.md

@@ -1,7 +1,27 @@
 # Logging != print()
 
-Logging is not the same as printing to the console. Logging is a more sophisticated way of recording events in a program.
-It is a way to track the flow of the program and to record errors and exceptions.
+Logging records the flow of a program, including its errors and exceptions, to the console and to a file at once. It is more than printing.
+
+## Usage
+
+Call `setup_logger` once at startup, then use the shared `logger` everywhere. The `time_it` decorator logs how long a function takes:
+
+```python
+from pathlib import Path
+
+from py_app_dev.core.logging import logger, setup_logger, time_it
+
+
+@time_it()
+def build() -> None:
+    logger.info("building ...")
+
+
+setup_logger(Path("build.log"))  # console + file
+build()
+```
+
+## Requirements
 
 ```{item} REQ-LOGGING_FILE-0.0.1 Print to file
 
@@ -41,7 +61,7 @@ It is a way to track the flow of the program and to record errors and exceptions
 ```
 
 :::{note}
-This module is based on the [loguru](https://github.com/Delgan/loguru) library, which is a Python logging library that provides powerful logging system.
+This module is built on the [loguru](https://github.com/Delgan/loguru) logging library.
 :::
 
 ## Current Status

docs/features/runnable.md

@@ -4,6 +4,45 @@ To optimize an application, you want to avoid executing tasks with high computat
 A simple way to avoid unnecessary executions is to check whether the inputs and outputs of a task have changed since the last execution.
 If there are no changes, the task is skipped, saving time and resources.
 
+## Usage
+
+Subclass `Runnable`, declare the task's inputs and outputs, then hand it to an `Executor`. The executor skips the task when nothing changed since the last run:
+
+```python
+from pathlib import Path
+
+from py_app_dev.core.runnable import Executor, Runnable
+
+
+class GenerateReport(Runnable):
+    def __init__(self, source: Path, report: Path) -> None:
+        super().__init__()
+        self.source = source
+        self.report = report
+
+    def get_name(self) -> str:
+        return "generate_report"
+
+    def run(self) -> int:
+        self.report.write_text(self.source.read_text().upper())
+        return 0
+
+    def get_inputs(self) -> list[Path]:
+        return [self.source]
+
+    def get_outputs(self) -> list[Path]:
+        return [self.report]
+
+
+executor = Executor(cache_dir=Path(".cache"))
+executor.execute(GenerateReport(Path("in.txt"), Path("out.txt")))  # runs
+executor.execute(GenerateReport(Path("in.txt"), Path("out.txt")))  # skipped, nothing changed
+```
+
+Pass `force_run=True` to `Executor` to run even when nothing changed, or `dry_run=True` to report what would run without touching the system.
+
+## Requirements
+
 ```{item} REQ-RUNNABLE-0.0.1 Executing a New Task
 
    Execute a new task to ensure it runs even in the absence of previous execution data.

docs/features/scoop_wrapper.md

@@ -3,6 +3,25 @@
 The [Scoop](https://scoop.sh/) package manager for Windows has certain limitations, particularly in handling of tool versions and path prioritization via shims.
 This module allows users to specify which versions of apps they want installed and actively manage the accessibility of these apps within their environment.
 
+## Usage
+
+Point `ScoopWrapper` at a scoop file (the JSON listing the apps and versions you want). `install` installs anything missing and returns every required app, located on disk:
+
+```python
+from pathlib import Path
+
+from py_app_dev.core.scoop_wrapper import ScoopWrapper
+
+apps = ScoopWrapper().install(Path("scoopfile.json"))
+for app in apps:
+    print(app.name, app.version)
+    print(app.get_all_required_paths())  # bin and env directories to put on PATH
+```
+
+Each returned `InstalledScoopApp` carries its `name`, `version`, install `path`, and the bin/env directories from its manifest.
+
+## Requirements
+
 ```{item} REQ-SCOOP-WRAPPER-0.0.1 Customized App Installation
 
    Allow users to specify which apps and versions to install via Scoop.

docs/getting_started/index.md

@@ -1,3 +1,29 @@
 # 🚀 Getting Started
 
-To be documented ...
+Add the package as a dependency of your project in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "py-app-dev",
+]
+```
+
+Every module shares one logging setup. This is the smallest useful program:
+
+```python
+from pathlib import Path
+
+from py_app_dev.core.logging import logger, setup_logger, time_it
+
+
+@time_it()
+def build() -> None:
+    logger.info("building ...")
+
+
+setup_logger(Path("build.log"))  # logs to console and to the file
+build()
+```
+
+From here, browse the [Features](../features/index.md) for the modules you need.

docs/internals/mvp/index.md

@@ -43,33 +43,11 @@ The Presenter subscribes to the Event Manager to handle these events and updates
       Presenter "1" *-- EventManager
 ```
 
-The implementation above uses the Model-View-Presenter (MVP) design pattern along with the Event Manager to handle events and communication between the components.
-Here are some advantages of this implementation:
-
-- **Separation of Concerns:**
-  : This pattern pattern separates the responsibilities of the View and Presenter into distinct components, which makes the code easier to read, test, and maintain.
-  The Event Manager also helps to decouple the components, making it easier to modify and extend the code without affecting other parts.
-- **Testability:**
-  : The Presenter acts as a mediator between the View and the underlying functionality, which allows for easy unit testing of the Presenter without needing to test the user interface.
-- **Flexibility:**
-  : It allows for different user interfaces to be used with the same underlying functionality.
-  For example, if we wanted to switch from a graphical user interface to a command-line interface, we could do so without affecting the underlying functionality of the application.
+Keeping the View and Presenter apart, with the Event Manager between them, makes the Presenter unit-testable without a user interface and lets the same logic drive a different View (for example, swapping a GUI for a command line).
 
 ## Event Manager
 
-The EventManager class is a utility class that can be used in conjunction with the Model-View-Presenter design pattern to facilitate communication between the View and the Presenter.
-Its primary purpose is to handle events that are raised by the View and forward them to the appropriate Presenter methods.
-
-By using the EventManager class, the View can raise events using the create_event_trigger method, and the Presenter can subscribe to those events using the subscribe method.
-When the event is triggered, the EventManager calls all of the registered callbacks for that event, allowing the Presenter to handle the event appropriately.
-The unsubscribe method can be used to remove callbacks from the list of subscribers if needed.
-
-It's worth noting that the EventManager class, as described above, is actually an implementation of the Observer design pattern.
-In this pattern, the EventManager acts as the Subject or Observable, while the callbacks registered through the subscribe method serve as the Observers.
-
-When an event is triggered, the EventManager notifies all registered Observers by calling their respective callback functions. This decouples the components of the system and allows for easier maintenance and modifications in the future.
-
-By using the Observer pattern with the EventManager class, the View can raise events without knowing anything about the Presenter, and the Presenter can handle events without knowing anything about the View. This promotes a more modular and flexible architecture, making it easier to develop and maintain complex systems.
+The `EventManager` decouples the View from the Presenter: the View raises events with `create_event_trigger`, and the Presenter reacts to them with `subscribe`. When an event fires, the manager calls every registered callback; `unsubscribe` removes one. This is the Observer pattern, with the manager as the subject and the callbacks as the observers, so neither side needs to know about the other.
 
 ```{eval-rst}
 .. autoclass:: py_app_dev.mvp.event_manager::EventManager