Skip to content

USAGE_GUIDE.md

Latest commit

 

History

History
438 lines (331 loc) · 12.1 KB

USAGE_GUIDE.md

File metadata and controls

438 lines (331 loc) · 12.1 KB

Yandex Disk Menu - Usage Guide & Examples

This guide provides detailed installation examples, file manager-specific setup, and troubleshooting instructions.

📋 Overview: For project introduction and quick start, see README. For developer workflow and directory map, see Developer Guide. For Python user-facing technical details, see Python README.

🚀 Quick Command Reference

Consider GNOME/GTK Beta status, so it may not work as intended

Desktop Environment Recommended Setup Command
Any Desktop (Auto-detect) make install-system-deps && make install && make configure
Existing YA_DISK_ROOT make install-system-deps && make install && make configure-skip-env
Shell only (KDE) ./setup.sh

Common Use Cases

🎯 Most users: Use auto-detection (make configure)
⚡ Minimal setup: Use shell version (./setup.sh)
🔧 Granular control: Use individual component commands (gnome-install, gnome-ext-install)
🚫 Existing config: Use skip environment variables (make configure-skip-env)

🔧 Installation Options Comparison

Method Speed Features When to Use
Auto-detect (make configure) Fast Auto-detects your environment Recommended - Optimized setup, good for quick start
Skip environment variables (make configure-skip-env) Fast Auto-detects your environment Good for update existing setup after get recent update, e.g. git pull
Shell only (KDE) (./setup.sh) Fastest Basic features, minimal deps Lightweight systems, KDE only
Manual components Slower Full control over components Troubleshooting, custom setups

🖥️ File Manager-Specific Installation

KDE Dolphin (Primary Support)

Setup:

make install-system-deps  # Install KDE dependencies (notification, clipboard tools)
make install && make configure  # Auto-detects KDE and configures for Dolphin

Alternative (Shell only):

./setup.sh  # Lightweight shell version

Menu Location: Right-click on files → "YaDisk" or "YaDisk (Python)"

GNOME/GTK (Beta): Files/Nautilus, Caja (MATE), Nemo (Cinnamon), Thunar (XFCE)

💡 Integration Types:

  • make gnome-install - Scripts/actions integration (works everywhere, basic functionality)
  • make gnome-ext-install - Python extensions integration (enhanced functionality, requires specific packages)

Setup:

# Install GNOME dependencies and configure everything at once
make install-system-deps
make install && make configure  # Auto-detects GNOME and configures all file managers

# Or skip environment variable setup
make install && make configure-skip-env

For manual control you can use component commands:

make gnome-install        # 1 Scripts/actions for GNOME file managers
make gnome-ext-install    # 2 Optional Python extensions when supported
make gnome-status         # 3 Check scripts/actions status
make gnome-ext-status     # 4 Check extensions status
nautilus -q               # 5 Restart file manager
caja -q
nemo -q

Note: Thunar uses custom actions (XML), not Python extensions.

Menu Locations:

  • Scripts: Files → Scripts → "YaDisk – ..." (always available)
  • Extension: Right-click context menu → "YaDisk" (enhanced integration)

🔧 Configuration Commands

Main Configuration

make configure            # Auto-detect desktop and configure (recommended)
make configure-skip-env   # Auto-detect desktop, skip environment variables

What make configure does:

  • Detects desktop environment (KDE, GNOME, etc.)
  • KDE: Configures Dolphin service menus
  • GNOME: Installs scripts/actions + optional Python extensions
  • Unknown: Universal configuration with manual file manager setup

Component Commands (Advanced Users)

# GNOME/GTK file managers (manual control)
make gnome-install        # Install scripts/actions for all file managers
make gnome-ext-install    # Install Python extensions for all supported file managers
make gnome-status         # Check scripts/actions status
make gnome-ext-status     # Check Python extensions status
make gnome-uninstall      # Remove all scripts/actions
make gnome-ext-uninstall  # Remove all Python extensions

# Status & Maintenance
make status               # Overall installation status
make test                 # Run all tests
make clean                # Clean build files
make uninstall            # Remove Python version

📱 System Requirements

Clipboard Support

  • X11: Uses xclip for clipboard operations
  • Wayland: Uses wl-clipboard for clipboard operations
  • Python: Uses pyclip (auto-detects and switches between xclip and wl-clipboard)

Dependencies by Desktop

Desktop Required Optional Extensions
KDE kdialog, xclip/wl-clipboard None
GNOME libnotify-bin, clipboard tools python3-nautilus, python3-gi
Others notify-send, clipboard tools Desktop-specific packages

Automated Installation

make install-system-deps  # Detects your distribution and desktop

Supported Package Managers:

  • APT (Ubuntu/Debian)
  • DNF (Fedora/Red Hat)
  • Pacman (Arch Linux)

🎯 Examples

# Fresh install (any desktop)
make install-system-deps && make install && make configure

# Existing YA_DISK_ROOT
git reset --hard HEAD && git pull && make install && make configure-skip-env

# Shell version only (KDE)
./setup.sh

Component-Specific Use Cases

Basic Integration (GNOME/GTK)

make gnome-install        # Scripts/actions for Nautilus, Nemo, Caja
# Result: Menu items available in all supported file managers

Use Case: Enhanced Integration (Python Extensions)

make gnome-ext-install    # Python extensions for all supported file managers
# Result: Advanced integration where supported (auto-detects capabilities)

Use Case: Development Testing

# Install everything for comprehensive testing
make gnome-install        # All scripts/actions
make gnome-ext-install    # All Python extensions
make gnome-status         # Check scripts status
make gnome-ext-status     # Check extensions status

Use Case: Troubleshooting

# Check what's installed
make status               # Overall Python setup status
make gnome-status         # Scripts/actions status for all file managers
make gnome-ext-status     # Python extensions status for all file managers

# Reinstall if broken
make gnome-uninstall && make gnome-install
make gnome-ext-uninstall && make gnome-ext-install

Daily Usage Examples

Basic File Operations:

  1. Publish File: Right-click file → YaDisk → "Publish (COM)" or "Publish (RU)"
  2. Copy to Stream: Right-click file → YaDisk → "Copy to Stream"
  3. Save Clipboard: Right-click anywhere → YaDisk → "Save Clipboard"

Batch Operations (Python Version):

  • Select multiple files → Right-click → YaDisk → Choose action
  • Intelligent error handling continues with remaining files if some fail

Menu Actions Available:

Action Description Location
Publish (COM) Create public .com link and copy to clipboard All file managers
Publish (RU) Create public .ru link and copy to clipboard All file managers
Save Clipboard Save clipboard content to stream directory Background click
Save & Publish Clipboard Save clipboard and create public link Background click
Copy to Stream Copy selected files to stream directory Selected files
Move to Stream Move selected files to stream directory Selected files
Unpublish Remove public link for file Single file
Unpublish All Copies Remove public links for file and all copies Single file

🛠️ Troubleshooting

Menu Not Appearing

KDE Dolphin:

# Check service menu files
ls ~/.local/share/kservices5/ServiceMenus/ydpublish*.desktop # older Plasma versions
ls ~/.local/share/kio/servicemenus

# Restart Dolphin
dolphin --replace &

GNOME Files:

# Check scripts installation
ls ~/.local/share/nautilus/scripts/YaDisk*

# Restart Nautilus
nautilus -q

Other File Managers:

# Check status for all
make gnome-status

# Verify dependencies
make install-system-deps

Python Version Issues

Virtual Environment:

# Recreate if corrupted
rm -rf venv
make install

# Check Python wrapper
ls -la ydmenu-py-env
which ydmenu-py-env

Dependencies:

# Check system dependencies
python setup.py --check-deps

# Reinstall if needed
make clean && make install

Environment Variables

Check Setup:

# Verify variables
echo $YA_DISK_ROOT
echo $YADISK_MENU_VERSION

# Check .env file (Python version)
cat .env

Reset Environment:

# Shell version
sudo nano /etc/environment

# Python version  
./setup.py  # Reconfigure

Permission Issues

Fix Permissions:

# Make scripts executable
chmod +x ydmenu.py ydmenu.sh ydmenu-py-env

# Fix desktop files
chmod +x *.desktop

# GNOME scripts
chmod +x gnome/scripts/*

Yandex Disk Issues

Service Status:

# Check daemon
yandex-disk status

# Restart if needed
yandex-disk stop
yandex-disk start

# Check logs
tail -f ~/.yandex-disk.log

📊 Status & Maintenance

Check Installation Status

make status          # Overall status
make gnome-status    # GNOME/GTK file managers

Update/Reinstall

# Update dependencies
make install-system-deps

# Reinstall Python version
make clean && make install && make configure

# Update desktop integration
make desktop-aware-install

Uninstall

# Remove Python version
make uninstall

# Remove GNOME integration
make gnome-uninstall
make gnome-ext-uninstall

Troubleshooting

Common Issues and Solutions

1. Desktop Menu Not Appearing

# Check symlinks
make status

# Restart Dolphin
killall dolphin && dolphin &

# Verify KDE directories exist
mkdir -p ~/.local/share/kservices5/ServiceMenus/
mkdir -p ~/.local/share/kio/servicemenus/

2. Python Version Not Working

# Check virtual environment
ls venv/bin/python

# Test wrapper script
ydmenu-py-env --help

# Check dependencies
make install-system-deps
make install

3. Permission Errors

# Make scripts executable
chmod +x ydmenu.py setup.py ydmenu-py-env ydmenu.sh setup.sh

# Check file ownership
ls -la ydmenu*

4. Yandex Disk Service Issues

# Check service status
yandex-disk status

# Start service if needed
yandex-disk start

# Check daemon configuration
yandex-disk status --tray

5. Environment Variables Not Set

# Check environment
echo $YA_DISK_ROOT

# Reload environment (after setup)
source /etc/environment

# Log out and back in for system-wide effect

Debugging Tips

  1. Check logs: All operations log to $YA_DISK_ROOT/yaMedia.log
  2. Test manually: Run scripts directly to see detailed error messages
  3. Verify paths: Ensure all paths in environment variables exist
  4. Check dependencies: Use make status to verify all system dependencies

Performance Comparison

Aspect Shell Version Python Version
Startup Time ~0.1s ~0.3s (includes venv)
Memory Usage ~2MB ~15MB
Dependencies System tools only Python + click + PyQt5
Error Handling Basic Comprehensive
Extensibility Limited High
Testing Manual Unit tests

🔗 Related Documentation