doc: Documentation fixes and improvements (#290)

* doc: Added brokers logos to the documentation

Added a script to help generating the broker logos with the proper sizes to be embedded in the documentation.

* doc: Improved broker login and settings documentation

Add screenshots and provide a more user oriented documentation

* doc: Fixed documentation broken links

Some of the documentation links were broken. This PR fixes those broken links, and adds tooling to validate the links are always correct

Author: ctasada

.gitignore

@@ -58,16 +58,17 @@ ENV/
 .idea/
 *.iml
 .claude/
+.vscode/
 
 # Project-specific
 config/*
 !config/config.json.template
-/import/
-portfolio-performance/*.csv
-portfolio-performance/*.pdf
 
 # IBKR certificates
 *.pem
 
 # nektos/act
 .actrc
+
+# lycheecache (Markdown Link Checker)
+.lycheecache

.pre-commit-config.yaml

@@ -36,6 +36,17 @@ repos:
         language: system
         stages: [pre-commit]
 
+  - repo: https://github.com/lycheeverse/lychee
+    rev: lychee-v0.22.0
+    hooks:
+      - id: lychee
+        name: Check Markdown Links
+        types: [markdown]
+        args:
+          - --config=lychee.toml
+          - --no-progress
+        stages: [pre-commit]
+
   # Optional: Check Django migrations
   - repo: local
     hooks:

AGENTS.md

@@ -644,13 +644,19 @@ class PortfolioEntry:
   - `make lint-fix` — Automatically fix Python code style issues and format code.
 - **Check Markdown files:**
   - `make markdown-check` — Check Markdown files for style issues.
+  - `make markdown-links-check` — Check links and images in Markdown files (validates URLs and local file references).
 - **Auto-fix Markdown files:**
   - `make markdown-fix` — Automatically fix Markdown style issues.
 
 ### Markdown Standards
 
 - **HTML is NOT allowed** - Use pure Markdown syntax only
 - Markdown files are linted using `pymarkdown` (run `make markdown-check` to verify)
+- **Links and images are validated** - All links and images are checked using `lychee` (run `make markdown-links-check` to verify)
+  - Broken links will fail pre-commit hooks
+  - Both local and remote links are validated
+  - Image file references are verified
+  - **Installation required**: `brew install lychee` (macOS) or see [Lychee Installation](https://github.com/lycheeverse/lychee?tab=readme-ov-file#installation) for other platforms
 - **Image sizing:** Standard Markdown does not support image sizing. To resize images:
   - Resize the actual image file itself using image editing tools
   - Use a smaller version of the image file if available
@@ -693,13 +699,19 @@ class PortfolioEntry:
    ```
    Ensures all tests pass. Fix broken tests or add new tests for new functionality.
 
-4. **Check Dependencies (RECOMMENDED)**
+4. **Check Markdown Links (REQUIRED if markdown changed)**
+   ```bash
+   make markdown-links-check
+   ```
+   Only if you modified or added markdown files. Validates all links and image references.
+
+5. **Check Dependencies (RECOMMENDED)**
    ```bash
    make check-dependencies
    ```
    Only if you added or removed dependencies.
 
-5. **Run Pre-commit Hooks (REQUIRED)**
+6. **Run Pre-commit Hooks (REQUIRED)**
    ```bash
    make pre-commit-run
    ```

CONTRIBUTING.md

@@ -93,7 +93,7 @@ Want to add support for a new broker? See our:
 2. **Clone your fork:**
 
    ```bash
-   git clone https://github.com/YOUR-USERNAME/stonks-overwatch.git
+   git clone https://github.com/YOUR_USERNAME/stonks-overwatch.git
    cd stonks-overwatch
    ```
 
@@ -268,7 +268,7 @@ class PortfolioService:
 - **Error handling**: Use custom exceptions with proper error messages
 - **Logging**: Use structured logging with appropriate log levels
 
-> **Note for AI Agents:** See [`AGENTS.md`](../AGENTS.md) for detailed architecture patterns, code examples, and AI-specific guidance.
+> **Note for AI Agents:** See [`AGENTS.md`](./AGENTS.md) for detailed architecture patterns, code examples, and AI-specific guidance.
 
 ## Testing
 

Makefile

@@ -60,7 +60,7 @@ RESET := \033[0m
 #==============================================================================
 
 .PHONY: help install update clean
-.PHONY: lint lint-check lint-fix markdown-check markdown-fix license-check generate-third-party check-dependencies scan
+.PHONY: lint lint-check lint-fix markdown-check markdown-fix markdown-links-check license-check generate-third-party check-dependencies scan
 .PHONY: migrate collectstatic runserver start run test coverage
 .PHONY: docker-build docker-run docker-shell docker-clean
 .PHONY: briefcase-create briefcase-update briefcase-run briefcase-package briefcase-clean
@@ -135,6 +135,17 @@ markdown-fix: ## Fix Markdown files automatically
 	@echo -e "$(BOLD)$(GREEN)Fixing Markdown files...$(RESET)"
 	poetry run pymarkdown --config=pyproject.toml fix -r README.md CHANGELOG.md ./docs
 
+markdown-links-check: ## Check links and images in Markdown files
+	@echo -e "$(BOLD)$(BLUE)Checking Markdown links and images...$(RESET)"
+	@if command -v lychee >/dev/null 2>&1; then \
+		lychee --config lychee.toml README.md CHANGELOG.md docs/; \
+	else \
+		echo -e "$(BOLD)$(RED)Error: lychee is not installed$(RESET)"; \
+		echo -e "$(YELLOW)Install it with: brew install lychee (macOS) or cargo install lychee (cross-platform)$(RESET)"; \
+		echo -e "$(YELLOW)Or download from: https://github.com/lycheeverse/lychee/releases$(RESET)"; \
+		exit 1; \
+	fi
+
 license-check: ## Check license compatibility
 	@echo -e "$(BOLD)$(BLUE)Checking license compatibility...$(RESET)"
 	poetry run licensecheck
@@ -339,6 +350,16 @@ generate-images: ## Generate images for browsers and Briefcase
 		exit 1; \
 	fi
 
+generate-docs-broker-icons: ## Generate broker icons for documentation (sidebar and docs pages)
+	@echo -e "$(BOLD)$(BLUE)Generating broker icons for documentation...$(RESET)"
+	@if [ -f "scripts/generate_docs_broker_icons.sh" ]; then \
+		chmod +x scripts/generate_docs_broker_icons.sh; \
+		./scripts/generate_docs_broker_icons.sh; \
+	else \
+		echo -e "$(RED)Error: scripts/generate_docs_broker_icons.sh not found$(RESET)"; \
+		exit 1; \
+	fi
+
 #==============================================================================
 ##@ Git Hooks
 #==============================================================================

README.md

@@ -54,17 +54,19 @@
 
 ## Screenshots
 
-![Dashboard Screenshot](docs/images/dashboard.png)
+![Broker Selector Screenshot](docs/images/screenshots/broker-selector.png)
+*Broker Selector and login dialog.*
+![Dashboard Screenshot](docs/images/screenshots/dashboard.png)
 *Dashboard view showing portfolio overview and performance metrics.*
-![Portfolio Screenshot](docs/images/portfolio.png)
+![Portfolio Screenshot](docs/images/screenshots/portfolio.png)
 *Detailed portfolio breakdown with asset allocation and recent transactions.*
-![Diversification Screenshot](docs/images/diversification.png)
+![Diversification Screenshot](docs/images/screenshots/diversification.png)
 *Visual representation of asset diversification across different classes.*
-![Dividends Screenshot](docs/images/dividends.png)
+![Dividends Screenshot](docs/images/screenshots/dividends.png)
 *Dividend tracking and upcoming payments overview.*
-![Dividends Calendar Screenshot](docs/images/dividends-2.png)
+![Dividends Calendar Screenshot](docs/images/screenshots/dividends-2.png)
 *Calendar view of upcoming dividend payments.*
-![Fees Screenshot](docs/images/fees.png)
+![Fees Screenshot](docs/images/screenshots/fees.png)
 *Analysis of fees incurred across different brokers.*
 
 ## Quick Start

docs/ARCHITECTURE_AUTHENTICATION.md

@@ -81,7 +81,7 @@ The authentication system consists of three main service layers:
 2. **Interface Layer**: Type-safe contracts for all services
 3. **Implementation Layer**: Concrete service implementations
 
-> **📖 Pattern Details:** See [Architecture Overview](ARCHITECTURE.md#factory-pattern) for more on the factory pattern implementation.
+> **📖 Pattern Details:** See [Architecture Overview](ARCHITECTURE.md#3-factory-pattern) for more on the factory pattern implementation.
 
 #### Service Interfaces