diff --git a/README.md b/README.md index ee27f48..e627fbe 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ License + + Read the Docs +

diff --git a/README/README_zh-CN.md b/README/README_zh-CN.md index 2a8059e..1508d77 100644 --- a/README/README_zh-CN.md +++ b/README/README_zh-CN.md @@ -21,6 +21,9 @@ License + + Read the Docs +

diff --git a/README/README_zh-TW.md b/README/README_zh-TW.md index 94c8248..380fec1 100644 --- a/README/README_zh-TW.md +++ b/README/README_zh-TW.md @@ -21,6 +21,9 @@ License + + Read the Docs +

diff --git a/docs/source/conf.py b/docs/source/conf.py index 73bfeae..d343ee6 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,15 +1,8 @@ # Configuration file for the Sphinx documentation builder. # -# This file only contains a selection of the most common options. For a full -# list see the documentation: +# For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# import os import sys from pathlib import Path @@ -20,37 +13,24 @@ # -- Project information ----------------------------------------------------- - project = "JEditor" -copyright = "2020 ~ Now, JE-Chen" +copyright = "2021 ~ Present, JE-Chen" author = "JE-Chen" - -# The full version, including alpha/beta/rc tags -release = "0.0.0.1" +release = "1.0.10" # -- General configuration --------------------------------------------------- -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named "sphinx.ext.*") or your custom -# ones. extensions = [] -# Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. exclude_patterns = [] # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# html_theme = "sphinx_rtd_theme" - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ["_static"] + +# -- Internationalization ---------------------------------------------------- + +locale_dirs = ["locale/"] +gettext_compact = False diff --git a/docs/source/docs/Eng/ai_assistant.rst b/docs/source/docs/Eng/ai_assistant.rst new file mode 100644 index 0000000..4741fb4 --- /dev/null +++ b/docs/source/docs/Eng/ai_assistant.rst @@ -0,0 +1,59 @@ +AI Assistant +============= + +JEditor integrates an AI-powered chat assistant using `LangChain `_ +and OpenAI-compatible APIs. The AI panel allows you to have conversations with a large language +model directly within the editor. + +Setup +------ + +Before using the AI assistant, you need to configure it: + +1. Open the AI configuration dialog from the menu +2. Set the following parameters: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Setting + - Description + * - **API Base URL** + - The API endpoint (e.g., ``https://api.openai.com/v1``) + * - **API Key** + - Your OpenAI API key + * - **Model** + - The model to use (e.g., ``gpt-3.5-turbo``, ``gpt-4``, or any custom model) + * - **System Prompt** + - A template that sets the AI's behavior and context + +Configuration is saved to ``.jeditor/ai_config.json`` and persists between sessions. + +You can also configure the API key via environment variables. + +Chat Interface +--------------- + +The AI chat panel provides: + +- **Message history** — Scrollable chat history with all previous messages +- **Input field** — Type your prompt at the bottom of the panel +- **Font size adjustment** — Customize the chat panel's font size +- **Read-only message area** — Chat history is displayed in a read-only area + +Async Communication +-------------------- + +AI requests are handled asynchronously to keep the editor responsive: + +- Messages are sent to the AI in a background thread +- Responses are pulled back using a configurable timer interval +- A message queue ensures orderly communication +- The UI remains fully interactive while waiting for responses + +Error Handling +--------------- + +If the AI request fails (e.g., network error, invalid API key), JEditor shows a clear error +dialog describing the problem. The chat session continues to work after resolving the issue. diff --git a/docs/source/docs/Eng/api_reference.rst b/docs/source/docs/Eng/api_reference.rst new file mode 100644 index 0000000..237457b --- /dev/null +++ b/docs/source/docs/Eng/api_reference.rst @@ -0,0 +1,259 @@ +API Reference +============== + +JEditor exposes a public Python API that allows you to use it as a library, extend its +functionality, or integrate it into your own applications. + +Starting the Editor +-------------------- + +.. code-block:: python + + from je_editor import start_editor + + start_editor() + +Launches the full JEditor application. This is the simplest way to start the editor +programmatically. + +Core Classes +------------- + +EditorMain +^^^^^^^^^^^ + +The main window class that contains the entire editor UI. + +.. code-block:: python + + from je_editor import EditorMain + +EditorWidget +^^^^^^^^^^^^^ + +The code editor widget (single editor tab) — a customized ``QPlainTextEdit``. + +.. code-block:: python + + from je_editor import EditorWidget + +FullEditorWidget +^^^^^^^^^^^^^^^^^ + +A complete editor widget with line numbers, syntax highlighting, and output display, +suitable for embedding in dock panels. + +.. code-block:: python + + from je_editor import FullEditorWidget + +MainBrowserWidget +^^^^^^^^^^^^^^^^^^ + +The embedded web browser widget. + +.. code-block:: python + + from je_editor import MainBrowserWidget + +Extending the Editor with Custom Tabs +--------------------------------------- + +Use ``EDITOR_EXTEND_TAB`` to add custom tabs to JEditor: + +.. code-block:: python + + from je_editor import start_editor, EDITOR_EXTEND_TAB + + EDITOR_EXTEND_TAB.update({"My Tab": MyCustomWidget}) + + start_editor() + +See :doc:`how_to_extend_using_pyside` for a complete example. + +Process Managers +----------------- + +ExecManager +^^^^^^^^^^^^ + +Manages program execution (running Python scripts and compiled binaries). + +.. code-block:: python + + from je_editor import ExecManager + +ShellManager +^^^^^^^^^^^^^ + +Manages shell command execution. + +.. code-block:: python + + from je_editor import ShellManager + +Syntax Highlighting +-------------------- + +PythonHighlighter +^^^^^^^^^^^^^^^^^^ + +The built-in Python syntax highlighter. + +.. code-block:: python + + from je_editor import PythonHighlighter + +syntax_extend_setting_dict / syntax_rule_setting_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Dictionaries that define syntax keywords and rules for the highlighter. + +.. code-block:: python + + from je_editor import syntax_extend_setting_dict, syntax_rule_setting_dict + +Settings +--------- + +user_setting_dict +^^^^^^^^^^^^^^^^^^ + +Dictionary containing all user settings (font, language, theme, etc.). + +.. code-block:: python + + from je_editor import user_setting_dict + +user_setting_color_dict +^^^^^^^^^^^^^^^^^^^^^^^^ + +Dictionary containing all color settings. + +.. code-block:: python + + from je_editor import user_setting_color_dict + +Multi-Language +--------------- + +language_wrapper +^^^^^^^^^^^^^^^^^ + +A function that returns the translated string for a given key, based on the current language. + +.. code-block:: python + + from je_editor import language_wrapper + + label = language_wrapper("file_menu_label") # Returns "File" or translated equivalent + +english_word_dict / traditional_chinese_word_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Built-in translation dictionaries. + +.. code-block:: python + + from je_editor import english_word_dict, traditional_chinese_word_dict + +Plugin API +----------- + +Programming Language Plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_programming_language, + get_programming_language_plugin, + get_all_programming_language_suffixes, + ) + +- ``register_programming_language(suffix, syntax_words, syntax_rules=None)`` — Register a new language +- ``get_programming_language_plugin(suffix)`` — Get the plugin for a file extension +- ``get_all_programming_language_suffixes()`` — List all registered extensions + +Natural Language Plugins +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_natural_language, + get_natural_language_plugin, + get_all_natural_languages, + ) + +- ``register_natural_language(language_key, display_name, word_dict)`` — Register a translation +- ``get_natural_language_plugin(language_key)`` — Get a translation dictionary +- ``get_all_natural_languages()`` — List all registered languages + +Run Configuration Plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_plugin_run_config, + get_all_plugin_run_configs, + get_plugin_run_config_by_suffix, + ) + +- ``register_plugin_run_config(config)`` — Register a run configuration +- ``get_all_plugin_run_configs()`` — List all run configurations +- ``get_plugin_run_config_by_suffix(suffix)`` — Get the run config for a file extension + +Plugin Metadata +^^^^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_plugin_metadata, + get_all_plugin_metadata, + ) + +- ``register_plugin_metadata(name, author, version)`` — Register plugin info +- ``get_all_plugin_metadata()`` — List all registered plugin metadata + +Plugin Loader +^^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import load_external_plugins + + load_external_plugins() + +Scans the ``jeditor_plugins/`` directory and loads all discovered plugins. + +Logging +-------- + +.. code-block:: python + + from je_editor import jeditor_logger + + jeditor_logger.info("Custom log message") + +The ``jeditor_logger`` is a standard Python logger that writes to ``JEditor.log``. + +Exceptions +----------- + +JEditor defines a hierarchy of custom exceptions: + +.. code-block:: python + + from je_editor import ( + JEditorException, # Base exception + JEditorExecException, # Execution errors + JEditorRunOnShellException, # Shell execution errors + JEditorSaveFileException, # File save errors + JEditorOpenFileException, # File open errors + JEditorContentFileException, # File content errors + JEditorCantFindLanguageException, # Language not found + JEditorJsonException, # JSON parsing errors + ) diff --git a/docs/source/docs/Eng/browser.rst b/docs/source/docs/Eng/browser.rst new file mode 100644 index 0000000..fb26ea7 --- /dev/null +++ b/docs/source/docs/Eng/browser.rst @@ -0,0 +1,51 @@ +Built-in Browser +================= + +JEditor includes an embedded web browser, allowing you to browse documentation, search +the web, and view web content — all without leaving the editor. + +Navigation +----------- + +The browser provides a full navigation toolbar: + +- **URL / Search bar** — Enter a URL or search query directly +- **Back / Forward** — Navigate through browsing history +- **Reload** — Refresh the current page +- **Stop** — Cancel loading the current page + +Search +------- + +**In-page search:** + +- Press ``Ctrl+F`` to open the in-page text search +- Find text within the current web page + +**Web search:** + +- Type a search query (not a URL) in the address bar +- JEditor will search using the configured search engine (Google by default) + +Browser Tabs +------------- + +You can open multiple browser instances: + +- **Tab menu** — Add a new browser tab (WEB Tab) +- **Dock menu** — Open a browser as a dockable panel +- **Stack Overflow tab** — Dedicated tab that opens Stack Overflow directly + +Download Tracking +------------------ + +The browser includes a download tracking window that shows the progress of file downloads. + +Features +--------- + +- Full web browsing capabilities +- JavaScript support (via WebKit/WebEngine) +- Link navigation and click handling +- Integrates with the editor's tab and dock system +- Customizable search engine prefix diff --git a/docs/source/docs/Eng/code_execution.rst b/docs/source/docs/Eng/code_execution.rst new file mode 100644 index 0000000..694d15c --- /dev/null +++ b/docs/source/docs/Eng/code_execution.rst @@ -0,0 +1,103 @@ +Code Execution & Debugging +=========================== + +JEditor includes a built-in code execution engine that supports running Python scripts, +compiled languages, and arbitrary shell commands — all without leaving the editor. + +Running Python Scripts +----------------------- + +Press **F5** to run the current Python file. JEditor will: + +1. Detect the Python interpreter (or virtual environment if present) +2. Execute the script in a background process +3. Stream real-time output to the result panel +4. Display errors in red for easy identification + +**Virtual Environment Support:** + +JEditor automatically detects ``venv`` directories in the project root and uses the +virtual environment's Python interpreter for execution, ensuring correct package resolution. + +You can also manually select a Python interpreter from the **Python Env** menu. + +Debugging +---------- + +Press **F9** to launch the current Python file in debug mode: + +- Python debugger (pdb) integration +- Variable inspection during execution (see Variable Inspector below) +- Step-through debugging capabilities + +Stop Execution +^^^^^^^^^^^^^^^ + +- **Shift+F5** — Stop all running processes +- Individual processes can also be stopped from the **Run** menu + +Running Other Languages +------------------------ + +Through the plugin system, JEditor supports running files in other languages: + +**Interpreted Languages** (run directly): + +- **Go** — ``go run file.go`` +- **Java** — ``java file.java`` + +**Compiled Languages** (compile then run): + +- **C** — ``gcc file.c -o file && ./file`` +- **C++** — ``g++ file.cpp -o file && ./file`` +- **Rust** — ``rustc file.rs -o file && ./file`` + +See :doc:`plugins` for details on adding run configurations for new languages. + +Shell Command Execution +------------------------ + +JEditor provides a built-in shell for running arbitrary commands: + +- Execute any shell/terminal command +- Cross-platform shell support: ``cmd``, ``PowerShell``, ``bash``, ``sh`` +- Select your preferred shell from the console widget's dropdown +- Real-time output streaming with color-coded results +- Stop running shell processes at any time + +Output Display +--------------- + +The result panel at the bottom of the editor shows execution output: + +- **Normal output** — displayed in the configured normal color +- **Error output** — displayed in red for easy identification +- **System messages** — displayed in a distinct color +- Output line limit is configurable (default: 200,000 lines) to prevent memory issues +- Clear results from the **Run** menu or via the console's Clear button + +Variable Inspector +------------------- + +The Variable Inspector provides runtime variable debugging in a table view: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Column + - Description + * - Name + - The variable name + * - Type + - The Python type of the variable + * - Value + - The current value (editable) + +Features: + +- Live variable inspection during script execution +- Filters out built-in variables (those starting with ``__``) +- Editable variable values with AST-based type conversion +- Dynamic namespace updates +- Sort and search capabilities diff --git a/docs/source/docs/Eng/code_quality.rst b/docs/source/docs/Eng/code_quality.rst new file mode 100644 index 0000000..9840b3b --- /dev/null +++ b/docs/source/docs/Eng/code_quality.rst @@ -0,0 +1,47 @@ +Code Quality & Formatting +========================== + +JEditor integrates multiple code quality tools to help you write clean, consistent code. + +YAPF Python Formatting +----------------------- + +`YAPF `_ (Yet Another Python Formatter) reformats Python code +to conform to the Google style guide. + +- **Shortcut:** ``Ctrl+Shift+Y`` +- Formats the entire file +- Applies consistent indentation, spacing, and line breaks +- Available from the **Check Code Style** menu + +PEP 8 Checking +---------------- + +JEditor integrates `pycodestyle `_ for PEP 8 compliance checking. + +- **Shortcut:** ``Ctrl+Alt+P`` +- Reports violations with line number and offset +- Customizable checks (W191 tab warnings are filtered by default) +- Available from the **Check Code Style** menu + +Ruff Linting +------------- + +`Ruff `_ is an extremely fast Python linter that runs automatically +in the background: + +- File system monitoring via ``watchdog`` detects when files change +- Linting runs in a background thread to keep the UI responsive +- Debounced file checks prevent excessive runs during rapid editing +- Comprehensive Python linting rules covering hundreds of checks +- Results are reported without blocking your workflow + +JSON Reformatting +------------------ + +JEditor can format and validate JSON files: + +- **Shortcut:** ``Ctrl+J`` +- Pretty-prints JSON with proper indentation +- Validates JSON syntax and reports errors +- Available from the **Check Code Style** menu diff --git a/docs/source/docs/Eng/configuration.rst b/docs/source/docs/Eng/configuration.rst new file mode 100644 index 0000000..8f8c659 --- /dev/null +++ b/docs/source/docs/Eng/configuration.rst @@ -0,0 +1,152 @@ +Configuration & Settings +========================= + +JEditor stores all user configuration in the ``.jeditor/`` directory under the current +working directory. Settings are automatically created on first launch and persist between sessions. + +Settings Files +--------------- + +user_setting.json +^^^^^^^^^^^^^^^^^^ + +The main settings file controls editor behavior and appearance: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Description + * - ``ui_font_family`` + - Font family for the main UI (menus, panels, dialogs) + * - ``ui_font_size`` + - Font size for the main UI + * - ``editor_font_family`` + - Font family for the code editor + * - ``editor_font_size`` + - Font size for the code editor + * - ``language`` + - UI language (``English``, ``Traditional Chinese``, or plugin-provided) + * - ``theme`` + - UI theme style (dark or light material themes) + * - ``encoding`` + - Default file encoding (``UTF-8``, ``GBK``, ``Latin-1``) + * - ``last_open_file`` + - Path to the last opened file (restored on launch) + * - ``python_compiler`` + - Path to the Python interpreter for code execution + * - ``max_output_lines`` + - Maximum lines in the output panel (default: 200,000) + * - ``recent_files`` + - List of recently opened files + * - ``indent_size`` + - Indentation size in spaces (default: 4) + +user_color_setting.json +^^^^^^^^^^^^^^^^^^^^^^^^ + +Controls the color scheme for the editor and output: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Setting + - Description + * - ``line_number_color`` + - RGB color for line number text + * - ``line_number_bg_color`` + - RGB color for the line number gutter background + * - ``current_line_color`` + - RGB color for the current line highlight + * - ``normal_output_color`` + - RGB color for normal output text + * - ``error_output_color`` + - RGB color for error output text + * - ``warning_output_color`` + - RGB color for warning output text + +All colors are specified as RGB arrays, e.g., ``[255, 0, 0]`` for red. + +ai_config.json +^^^^^^^^^^^^^^^ + +AI assistant configuration (see :doc:`ai_assistant` for details): + +- API base URL +- API key +- Model name +- System prompt template + +Theming +-------- + +JEditor supports dark and light themes via `qt-material `_: + +- **Default:** Dark Amber theme +- Switch themes from the **UI Style** menu +- Theme changes may require an application restart to fully take effect + +Font Customization +------------------- + +JEditor provides separate font settings for the UI and the code editor: + +**UI Font:** +- Change from the **File** menu +- Affects menus, panels, dialogs, and buttons +- Font family and size are independently configurable + +**Editor Font:** +- Change from the **Text** menu +- Affects the code editing area only +- Font family and size are independently configurable +- Changes take effect immediately + +Dockable Panels +----------------- + +JEditor's UI is built with Qt's dock widget system, making panels rearrangeable: + +- **Editor** — The main code editing area +- **Output** — Code execution results +- **File Tree** — Project directory browser +- **Console** — Shell / IPython console +- **AI Chat** — AI assistant panel +- **Git** — Git client panel +- **Browser** — Built-in web browser +- **Variable Inspector** — Runtime variable debugging + +All panels can be: + +- Dragged to different positions within the window +- Floated as independent windows +- Stacked as tabs in the same dock area +- Hidden or restored from the **Dock** menu + +System Tray +------------ + +JEditor supports system tray integration: + +- Minimize to the system tray instead of closing +- Tray icon with quick access to restore the window +- Continues running in the background when minimized + +Multi-Language UI +------------------ + +JEditor supports multiple UI languages: + +**Built-in Languages:** + +- English (default) +- Traditional Chinese (繁體中文) + +**Adding Languages via Plugins:** + +Additional languages can be added through the plugin system (see :doc:`plugins`). +Language changes take effect after restarting the application. + +Switch languages from the **Language** menu. diff --git a/docs/source/docs/Eng/console.rst b/docs/source/docs/Eng/console.rst new file mode 100644 index 0000000..d62367d --- /dev/null +++ b/docs/source/docs/Eng/console.rst @@ -0,0 +1,46 @@ +Console & REPL +=============== + +JEditor provides two types of interactive consoles: a Shell Console for running system commands, +and a Jupyter/IPython Console for interactive Python sessions. + +Shell Console +-------------- + +The built-in shell console lets you run system commands without leaving the editor. + +**Features:** + +- Execute any shell command directly +- **Command history** — Navigate previous commands with **Up/Down** arrow keys +- **Color-coded output:** + - Normal output in the default color + - Error output in red + - System messages in a distinct color +- **Working directory** — Select and display the current working directory +- **Shell selection** — Choose from: ``auto``, ``cmd``, ``PowerShell``, ``bash``, ``sh`` +- **Controls:** Run, Stop, and Clear buttons +- Output is limited to 10,000 lines to prevent memory issues +- Monospace font (Consolas or system default) + +**Shell Selector:** + +Use the dropdown at the top of the console widget to choose which shell to use. +The ``auto`` option selects the platform default (``cmd`` on Windows, ``bash`` on Linux/macOS). + +Jupyter / IPython Console +-------------------------- + +JEditor includes an embedded Jupyter/IPython console powered by ``qtconsole``: + +- Full in-process IPython kernel +- Rich interactive Python environment +- Tab completion and syntax highlighting +- Magic commands (``%timeit``, ``%run``, etc.) +- Qt event loop integration for seamless GUI interaction +- Proper resource cleanup when the editor closes + +**Usage:** + +Open the IPython console from the **Tab** or **Dock** menu. You get a fully functional +IPython session with access to all installed packages in your environment. diff --git a/docs/source/docs/Eng/editor.rst b/docs/source/docs/Eng/editor.rst new file mode 100644 index 0000000..8d54b8a --- /dev/null +++ b/docs/source/docs/Eng/editor.rst @@ -0,0 +1,147 @@ +Code Editor +============ + +JEditor's core is a powerful multi-tab code editor built on top of Qt's ``QPlainTextEdit``, designed +for speed, flexibility, and a smooth development experience. + +Multi-Tab Editing +------------------ + +Work on multiple files simultaneously using the tab-based interface: + +- Open multiple files in separate tabs +- Switch between tabs by clicking +- Close tabs individually +- Drag and drop files from the file system into the editor +- The current file path and tab state are tracked automatically + +File Operations +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Action + - Description + * - **New File** (``Ctrl+N``) + - Create a new empty file + * - **Open File** (``Ctrl+O``) + - Open an existing file and load it into a tab + * - **Open Folder** (``Ctrl+K``) + - Open a project folder and display it in the file tree + * - **Save File** (``Ctrl+S``) + - Save the current tab's content to disk + +Recent Files +^^^^^^^^^^^^^ + +JEditor keeps a list of recently opened files for quick access, available from the **File** menu. + +Auto-Save +^^^^^^^^^^ + +JEditor includes an automatic save feature that periodically saves your work: + +- Runs in a background thread per open file +- Configurable save interval +- Detects external file changes and handles conflicts +- Tracks file modification state + +Syntax Highlighting +-------------------- + +JEditor provides built-in Python syntax highlighting and supports additional languages through plugins. + +**Built-in Python Highlighting** includes: + +- Keywords (``if``, ``else``, ``for``, ``while``, ``def``, ``class``, etc.) +- Built-in functions (``print``, ``len``, ``range``, etc.) +- Strings (single-line and multi-line) +- Comments +- Decorators +- Numbers +- Customizable colors via the color settings + +**Plugin-based Language Support:** + +Additional languages can be added through the plugin system. Pre-built plugins are available for: + +- C (``.c``) +- C++ (``.cpp``, ``.cxx``, ``.cc``, ``.h``, ``.hpp``, ``.hxx``) +- Go (``.go``) +- Java (``.java``) +- Rust (``.rs``) + +See :doc:`plugins` for details on creating language plugins. + +Auto-Completion +---------------- + +JEditor integrates `Jedi `_ for intelligent Python code completion: + +- Context-aware suggestions based on the current code +- Supports virtual environment (venv) for accurate package completions +- Runs in a background thread so the UI stays responsive +- Configurable case-sensitivity and completion behavior + +Line Numbers +------------- + +The editor displays line numbers in a dedicated gutter on the left side: + +- Line numbers update dynamically as the document changes +- Customizable colors for line number text and background +- Current line number is highlighted for easy reference + +Current Line Highlight +----------------------- + +The line where the cursor is currently positioned is highlighted with a distinct background color, +making it easy to identify your editing position. The highlight color is customizable through the +color settings. + +File Tree +---------- + +When you open a folder (``Ctrl+K``), JEditor displays a file tree on the left side: + +- Browse the full directory structure of your project +- Click on any file to open it in a new editor tab +- Supports expanding and collapsing directories +- Scrollable navigation for large projects + +Encoding Support +----------------- + +JEditor supports multiple file encodings: + +- **UTF-8** (default) +- **GBK** +- **Latin-1** +- Automatic encoding detection when opening files +- Per-file encoding selection from the **File > Encoding** menu +- Encoding is preserved when saving files + +Search & Replace +----------------- + +JEditor provides powerful search and replace functionality: + +**File Search:** + +- Search within the current file +- Case-sensitive and case-insensitive options +- Regular expression (regex) support + +**Project-Wide Search:** + +- Search across all files in an opened folder +- Results displayed in a table with file path and line number +- Click on a result to navigate directly to the match +- Runs in a background thread for large codebases + +**Replace:** + +- Replace single occurrences or all matches at once +- Supports the same options as search (case, regex) diff --git a/docs/source/docs/Eng/eng_index.rst b/docs/source/docs/Eng/eng_index.rst index ae8690c..3fcc8a8 100644 --- a/docs/source/docs/Eng/eng_index.rst +++ b/docs/source/docs/Eng/eng_index.rst @@ -1,8 +1,27 @@ JEditor User Documentation ----- +=========================== + +.. image:: image/JEditor.png + :alt: JEditor Screenshot + :align: center + +**JEditor** is a modern, lightweight, and extensible code editor built entirely with Python and PySide6 (Qt for Python). +It is a complete rewrite of the original JEditor project, delivering **10x faster performance** while providing +a significantly richer feature set. .. toctree:: - :maxdepth: 4 + :maxdepth: 2 - how_to_use.rst - how_to_extend_using_pyside.rst \ No newline at end of file + getting_started + editor + code_execution + code_quality + git_integration + ai_assistant + console + browser + plugins + configuration + keyboard_shortcuts + api_reference + how_to_extend_using_pyside diff --git a/docs/source/docs/Eng/getting_started.rst b/docs/source/docs/Eng/getting_started.rst new file mode 100644 index 0000000..9cc95a2 --- /dev/null +++ b/docs/source/docs/Eng/getting_started.rst @@ -0,0 +1,104 @@ +Getting Started +================ + +System Requirements +-------------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Platform + - Version + * - Windows + - Windows 10 / 11 + * - macOS + - 10.5 ~ 11 Big Sur + * - Linux + - Ubuntu 20.04+ + * - Raspberry Pi + - 3B+ + * - Python + - 3.10, 3.11, 3.12 + +Installation +------------- + +**Install from PyPI:** + +.. code-block:: bash + + pip install je_editor + +**Install from source:** + +.. code-block:: bash + + git clone https://github.com/JE-Chen/je_editor.git + cd je_editor + pip install . + +Dependencies +^^^^^^^^^^^^^ + +JEditor will automatically install the following dependencies: + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Package + - Purpose + * - PySide6 + - GUI framework (Qt for Python) + * - qt-material + - Dark / Light material themes + * - yapf + - Python code formatting + * - jedi + - Python auto-completion + * - ruff + - Fast Python linter + * - gitpython + - Git operations + * - langchain / langchain_openai + - AI assistant (LLM integration) + * - watchdog + - File system monitoring + * - pycodestyle + - PEP 8 checking + * - qtconsole + - Jupyter / IPython console widget + * - frontengine + - Additional UI components + +Launching JEditor +------------------ + +**From the command line:** + +.. code-block:: bash + + python -m je_editor + +**As a Python library:** + +.. code-block:: python + + from je_editor import start_editor + + start_editor() + +After launching, JEditor opens with a dark-themed interface by default. You can change the theme +from the **UI Style** menu at any time. + +Project Structure +------------------ + +When JEditor starts, it creates a ``.jeditor/`` directory in the current working directory to store: + +- ``user_setting.json`` — UI preferences, font, language, recent files +- ``user_color_setting.json`` — Color scheme for editor and output +- ``ai_config.json`` — AI assistant configuration (if enabled) + +These files are created automatically on first launch. diff --git a/docs/source/docs/Eng/git_integration.rst b/docs/source/docs/Eng/git_integration.rst new file mode 100644 index 0000000..9173ebe --- /dev/null +++ b/docs/source/docs/Eng/git_integration.rst @@ -0,0 +1,92 @@ +Git Integration +================ + +JEditor includes a full-featured Git client with a graphical interface, powered by +`GitPython `_. All Git operations are performed +directly within the editor — no external tools required. + +Opening a Repository +--------------------- + +Open a Git repository from the Git panel. JEditor will: + +- Detect the repository root automatically +- Display the current branch in the toolbar +- Load the commit history +- Restore the last opened repository on next launch + +Branch Management +------------------ + +Manage branches directly from the editor: + +- **List all branches** — View local and remote branches in the branch tree +- **Switch branches** — Checkout any branch from the dropdown in the toolbar +- **Branch selector** — Quick branch switching via the toolbar dropdown + +Commit History +--------------- + +View the full commit history in a sortable table: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Column + - Description + * - SHA + - The commit hash (abbreviated) + * - Author + - The commit author + * - Date + - The commit date and time + * - Message + - The commit message + +**Commit Graph:** + +JEditor can display a visual commit graph showing branch relationships and merge history, +helping you understand the project's development timeline. + +Diff Viewer +------------ + +JEditor provides a powerful side-by-side diff viewer: + +- **Color-highlighted changes** — Added, removed, and modified lines are color-coded +- **Line numbers** — Both old and new versions show line numbers +- **Multi-file diff** — View changes across multiple files in a single session +- **Read-only display** — Diff view is read-only to prevent accidental edits + +Staging & Committing +--------------------- + +Perform full Git workflows within the editor: + +1. **Stage changes** — Select individual files to stage +2. **Unstage changes** — Remove files from the staging area +3. **Write commit message** — Enter a descriptive commit message +4. **Commit** — Create a new commit with the staged changes + +Remote Operations +------------------ + +Interact with remote repositories: + +- **Push** — Push local commits to the remote repository +- **Pull** — Pull the latest changes from the remote +- **Remote management** — Configure remote repository URLs +- **Tracking branch detection** — Automatically detects upstream branches + +Audit Logging +-------------- + +All Git operations are logged to ``audit.log`` for traceability: + +- **Timestamp** — When the operation occurred +- **Action** — What Git command was executed +- **Status** — Success or failure +- **Error details** — If the operation failed, the error message is logged + +The audit log is non-intrusive and never interrupts the UI, even if logging fails. diff --git a/docs/source/docs/Eng/how_to_extend_using_pyside.rst b/docs/source/docs/Eng/how_to_extend_using_pyside.rst index 3a8417b..b27889a 100644 --- a/docs/source/docs/Eng/how_to_extend_using_pyside.rst +++ b/docs/source/docs/Eng/how_to_extend_using_pyside.rst @@ -1,35 +1,81 @@ -How to extend using pyside ----- +Extending with PySide6 +======================= + +JEditor is built on PySide6 (Qt for Python), and you can extend it by adding custom +tabs or dock panels using your own Qt widgets. + +Adding a Custom Tab +-------------------- + +Use the ``EDITOR_EXTEND_TAB`` dictionary to register your custom widget as a new tab +in the editor. The key is the tab name, and the value is the widget class (not an instance). + +**Example:** .. code-block:: python - from PySide6.QtWidgets import QWidget, QGridLayout, QLineEdit, QPushButton, QLabel + from PySide6.QtWidgets import QWidget, QGridLayout, QLineEdit, QPushButton, QLabel + from je_editor import start_editor, EDITOR_EXTEND_TAB + + + class TestUI(QWidget): + """A simple custom widget with a text input and a submit button.""" + + def __init__(self): + super().__init__() + self.grid_layout = QGridLayout(self) + self.grid_layout.setContentsMargins(0, 0, 0, 0) + + self.label = QLabel("") + self.line_edit = QLineEdit() + self.submit_button = QPushButton("Submit") + self.submit_button.clicked.connect(self.show_input_text) - from je_editor import start_editor, EDITOR_EXTEND_TAB + self.grid_layout.addWidget(self.label, 0, 0) + self.grid_layout.addWidget(self.line_edit, 1, 0) + self.grid_layout.addWidget(self.submit_button, 2, 0) + def show_input_text(self): + self.label.setText(self.line_edit.text()) - # You can use you own QWidget - class TestUI(QWidget): - def __init__(self): - super().__init__() - self.grid_layout = QGridLayout(self) - self.grid_layout.setContentsMargins(0, 0, 0, 0) - self.grid_layout.setContentsMargins(0, 0, 0, 0) - self.label = QLabel("") - self.line_edit = QLineEdit() - self.submit_button = QPushButton("Submit") - self.submit_button.clicked.connect(self.show_input_text) - self.grid_layout.addWidget(self.label, 0, 0) - self.grid_layout.addWidget(self.line_edit, 1, 0) - self.grid_layout.addWidget(self.submit_button, 2, 0) + # Register the custom tab: {"tab_name": WidgetClass} + EDITOR_EXTEND_TAB.update({"test": TestUI}) - def show_input_text(self): - self.label.setText(self.line_edit.text()) + # Start the editor with the custom tab + start_editor() - # tab name: tab instance(QWidget) - EDITOR_EXTEND_TAB.update({"test": TestUI}) +After running this script, JEditor will include a "test" tab alongside the default tabs. + +How It Works +^^^^^^^^^^^^^ + +1. ``EDITOR_EXTEND_TAB`` is a dictionary that maps tab names to widget classes +2. JEditor creates an instance of each registered widget class when building the UI +3. The widget is added as a new tab in the tab bar +4. Your widget has full access to PySide6/Qt functionality + +Tips +^^^^^ + +- Your widget class must inherit from ``QWidget`` (or a subclass) +- Use layouts (``QGridLayout``, ``QVBoxLayout``, etc.) for responsive design +- You can access JEditor's internal components through the public API +- Multiple custom tabs can be registered by calling ``update()`` multiple times or + passing a dictionary with multiple entries + +Using JEditor Components +-------------------------- + +You can also use JEditor's individual components in your own PySide6 applications: + +.. code-block:: python - start_editor() + from je_editor import EditorWidget, MainBrowserWidget, FullEditorWidget +- ``EditorWidget`` — A standalone code editor widget +- ``FullEditorWidget`` — A complete editor with line numbers and output panel +- ``MainBrowserWidget`` — A standalone web browser widget +These widgets can be added to any PySide6 layout, making it easy to integrate +code editing or browsing capabilities into your own applications. diff --git a/docs/source/docs/Eng/how_to_use.rst b/docs/source/docs/Eng/how_to_use.rst deleted file mode 100644 index c59d39e..0000000 --- a/docs/source/docs/Eng/how_to_use.rst +++ /dev/null @@ -1,61 +0,0 @@ -How to use ----- - -* Modern Editor. -* Old JEditor remake. -* AutoSave, Encoding Feature. -* Multi program and shell runner. -* Including yapf python format checker. -* Including reformat JSON. -* Virtual Environment support. -* Dark & Light mode ui support. -* File tree support. -* Line code. -* Current line highlight. -* Python code highlight. -* Performance efficiency than old JEditor 1000%. -* OS Independent. -* JEditor defaults to using a dark interface as shown below: -.. image:: image/JEditor.png -* Menubar - * File Menu - * New File (Create new file) - * Open File (Open file and read content to code edit area) - * Save File (Save current code edit content to file) - * Font (Choose main UI font) - * Font Size (Choose main UI font size) - * Encoding (Choose program runner and shell runner encoding) - * Run Menu - * Run Program (Use program runner to run code edit content) - * Run On Shell (Use shell runner to run code edit content) - * Clean Result (Clean code or shell result) - * Stop Program (Stop program runner) - * Run Help Menu - * Run Help (Run help message) - * Shell Help (Shell help message) - * Text Menu - * Font (Choose editor default font) - * Font Size (Change editor default font size) - * Check Code Style Menu - * yapf (Check Python code style using yapf) - * Reformat JSON (Reformat and valid JSON) - * Help Menu - * GitHub (Open JEditor GitHub) - * Doc (Open JEditor doc) - * About (About JEditor message) - * Python Env Menu - * Create Venv (Try to create venv use shell runner) - * pip upgrade package (Try to pip upgrade package use shell runner) - * pip package (Try to pip package use shell runner) - * choose python interpreter (choose what interpreter will be used) - * Tab Menu - * Add Editor Tab (Open Editor tab) - * Add FrontEngine Tab (Open FrontEngine tab) - * Add WEB Tab (Open browser tab) - * Add Stackoverflow Tab (Open Stackoverflow tab) - * Dock Menu - * New Dock Browser (Open Browser tab) - * New Dock Stackoverflow (Open Stackoverflow tab) - * New Dock Editor (Open Editor tab) - * New Dock FrontEngine (Open FrontEngine tab) - * UI Style Menu (Include many ui user can use) diff --git a/docs/source/docs/Eng/keyboard_shortcuts.rst b/docs/source/docs/Eng/keyboard_shortcuts.rst new file mode 100644 index 0000000..a3fe50e --- /dev/null +++ b/docs/source/docs/Eng/keyboard_shortcuts.rst @@ -0,0 +1,81 @@ +Keyboard Shortcuts +==================== + +JEditor provides keyboard shortcuts for common operations, making your workflow faster +and more efficient. + +File Operations +---------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Shortcut + - Action + * - ``Ctrl+N`` + - Create a new file + * - ``Ctrl+O`` + - Open an existing file + * - ``Ctrl+K`` + - Open a folder (project) + * - ``Ctrl+S`` + - Save the current file + +Code Execution +--------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Shortcut + - Action + * - ``F5`` + - Run the current Python file + * - ``F9`` + - Debug the current Python file + * - ``Shift+F5`` + - Stop all running processes + +Code Quality +------------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Shortcut + - Action + * - ``Ctrl+Shift+Y`` + - Format Python code with YAPF + * - ``Ctrl+Alt+P`` + - Check PEP 8 compliance + * - ``Ctrl+J`` + - Reformat / validate JSON + +Browser +-------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Shortcut + - Action + * - ``Ctrl+F`` + - In-page text search (browser) + +Console +-------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Shortcut + - Action + * - ``Up`` + - Previous command in history + * - ``Down`` + - Next command in history diff --git a/docs/source/docs/Eng/plugins.rst b/docs/source/docs/Eng/plugins.rst new file mode 100644 index 0000000..e8a53b8 --- /dev/null +++ b/docs/source/docs/Eng/plugins.rst @@ -0,0 +1,336 @@ +Plugin System +============== + +JEditor features a comprehensive plugin system that allows you to extend the editor with new +programming language support, UI translations, and custom run configurations. + +Plugin Types +------------- + +JEditor supports four types of plugins: + +1. **Programming Language Plugins** — Add syntax highlighting for new languages +2. **Natural Language (Translation) Plugins** — Add UI translations +3. **Run Configuration Plugins** — Define how to execute files of specific types +4. **Plugin Metadata** — Version and author information for the Plugins menu + +Plugin Directory +----------------- + +Plugins are auto-discovered from the ``jeditor_plugins/`` directory under your working directory: + +.. code-block:: text + + working_directory/ + jeditor_plugins/ + my_syntax.py # Single-file plugin + my_language.py + my_package/ # Package plugin + __init__.py + +**Discovery Rules:** + +- Files starting with ``_`` or ``.`` are ignored +- Each plugin **must** define a ``register()`` function +- Package plugins use ``__init__.py`` as the entry point +- Duplicate plugin names are handled by first-found-wins + +Plugin Metadata +---------------- + +Each plugin can optionally define metadata that appears in the **Plugins** menu: + +.. code-block:: python + + PLUGIN_NAME = "My Plugin" # Display name + PLUGIN_AUTHOR = "Your Name" # Author + PLUGIN_VERSION = "1.0.0" # Version + +If omitted, the filename is used as the plugin name. + +Programming Language Plugin +---------------------------- + +Add syntax highlighting for any programming language. + +**API:** + +.. code-block:: python + + from je_editor.plugins import register_programming_language + + register_programming_language( + suffix=".ext", # File extension + syntax_words={...}, # Keyword groups + syntax_rules={...}, # Regex rules (optional) + ) + +**syntax_words format:** + +Define keyword groups with their highlight colors: + +.. code-block:: python + + from PySide6.QtGui import QColor + + syntax_words = { + "group_name": { + "words": ("keyword1", "keyword2", ...), + "color": QColor(r, g, b), + }, + # More groups... + } + +**syntax_rules format:** + +Define regex patterns for complex syntax elements (comments, strings, etc.): + +.. code-block:: python + + syntax_rules = { + "rule_name": { + "rules": (r"regex_pattern", ...), + "color": QColor(r, g, b), + }, + } + +**Full Example — Go Syntax Highlighting:** + +.. code-block:: python + + """Go syntax highlighting plugin.""" + from PySide6.QtGui import QColor + from je_editor.plugins import register_programming_language + + PLUGIN_NAME = "Go Syntax Highlighting" + PLUGIN_AUTHOR = "Your Name" + PLUGIN_VERSION = "1.0.0" + + go_syntax_words = { + "keywords": { + "words": ( + "break", "case", "chan", "const", "continue", + "default", "defer", "else", "fallthrough", "for", + "func", "go", "goto", "if", "import", + "interface", "map", "package", "range", "return", + "select", "struct", "switch", "type", "var", + ), + "color": QColor(86, 156, 214), + }, + "types": { + "words": ( + "bool", "byte", "complex64", "complex128", + "float32", "float64", "int", "int8", "int16", + "int32", "int64", "rune", "string", "uint", + "uint8", "uint16", "uint32", "uint64", "uintptr", + "error", "nil", "true", "false", "iota", + ), + "color": QColor(78, 201, 176), + }, + } + + go_syntax_rules = { + "single_line_comment": { + "rules": (r"//[^\\n]*",), + "color": QColor(106, 153, 85), + }, + } + + + def register() -> None: + register_programming_language( + suffix=".go", + syntax_words=go_syntax_words, + syntax_rules=go_syntax_rules, + ) + +**Multiple File Extensions:** + +If a language uses multiple extensions, register each one: + +.. code-block:: python + + def register() -> None: + for suffix in (".cpp", ".cxx", ".cc", ".h", ".hpp", ".hxx"): + register_programming_language( + suffix=suffix, + syntax_words=cpp_syntax_words, + syntax_rules=cpp_syntax_rules, + ) + +Natural Language (Translation) Plugin +--------------------------------------- + +Add UI translations for new languages. + +**API:** + +.. code-block:: python + + from je_editor.plugins import register_natural_language + + register_natural_language( + language_key="French", # Internal key + display_name="Francais", # Shown in Language menu + word_dict={...}, # Translation dictionary + ) + +The ``word_dict`` should contain the same keys as JEditor's built-in ``english_word_dict``. +Common keys include: + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Key + - Description + * - ``application_name`` + - Window title + * - ``file_menu_label`` + - File menu + * - ``run_menu_label`` + - Run menu + * - ``tab_name_editor`` + - Editor tab name + * - ``language_menu_label`` + - Language menu + * - ``help_menu_label`` + - Help menu + +For a complete list, refer to ``je_editor.utils.multi_language.english.english_word_dict`` +or the example plugin at ``exe/jeditor_plugins/french.py``. + +**Full Example — Japanese Translation:** + +.. code-block:: python + + """Japanese translation plugin.""" + from je_editor.plugins import register_natural_language + + PLUGIN_NAME = "Japanese Translation" + PLUGIN_AUTHOR = "Your Name" + PLUGIN_VERSION = "1.0.0" + + japanese_word_dict = { + "application_name": "JEditor", + "file_menu_label": "\u30d5\u30a1\u30a4\u30eb", + "run_menu_label": "\u5b9f\u884c", + "tab_name_editor": "\u30a8\u30c7\u30a3\u30bf", + "language_menu_label": "\u8a00\u8a9e", + # ... more keys + } + + + def register() -> None: + register_natural_language( + language_key="Japanese", + display_name="\u65e5\u672c\u8a9e", + word_dict=japanese_word_dict, + ) + +Run Configuration Plugin +-------------------------- + +Define how to execute files of specific types. + +**Interpreted Languages** (run directly): + +.. code-block:: python + + PLUGIN_RUN_CONFIG = { + "name": "Go", # Display name in menu + "suffixes": (".go",), # Supported file types + "compiler": "go", # Executable + "args": ("run",), # Args before file path + } + # Runs: go run file.go + +**Compiled Languages** (compile then run): + +.. code-block:: python + + PLUGIN_RUN_CONFIG = { + "name": "C (GCC)", + "suffixes": (".c",), + "compiler": "gcc", + "args": (), + "compile_then_run": True, # Compile first, then run + "output_flag": "-o", # Output binary flag + } + # Compiles: gcc file.c -o file + # Then runs: ./file (Linux/Mac) or file.exe (Windows) + +**Configuration Keys:** + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - Key + - Required + - Description + * - ``name`` + - Yes + - Display name in the Run menu + * - ``suffixes`` + - Yes + - Tuple of file extensions + * - ``compiler`` + - Yes + - Compiler or interpreter executable + * - ``args`` + - No + - Extra arguments before the file path + * - ``compile_then_run`` + - No + - If ``True``, compile first then execute the binary + * - ``output_flag`` + - No + - Output file flag (default ``"-o"``) + +Pre-built Plugins +------------------ + +JEditor ships with the following example plugins in ``exe/jeditor_plugins/``: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 25 25 + + * - Plugin + - Type + - File Extensions + - Run Support + * - C Syntax Highlighting + - Syntax + - ``.c`` + - GCC compile & run + * - C++ Syntax Highlighting + - Syntax + - ``.cpp``, ``.cxx``, ``.cc``, ``.h``, ``.hpp``, ``.hxx`` + - G++ compile & run + * - Go Syntax Highlighting + - Syntax + - ``.go`` + - ``go run`` + * - Java Syntax Highlighting + - Syntax + - ``.java`` + - ``java`` + * - Rust Syntax Highlighting + - Syntax + - ``.rs`` + - rustc compile & run + * - French Translation + - Language + - — + - — + +Plugin Browser +--------------- + +JEditor includes a Plugin Browser accessible from the **Plugin** menu: + +- Browse available plugins +- GitHub API integration for discovering community plugins +- View plugin metadata (name, author, version) diff --git a/docs/source/docs/Zh/ai_assistant.rst b/docs/source/docs/Zh/ai_assistant.rst new file mode 100644 index 0000000..90ef8d0 --- /dev/null +++ b/docs/source/docs/Zh/ai_assistant.rst @@ -0,0 +1,58 @@ +AI 助手 +======== + +JEditor 整合了基於 `LangChain `_ 和 OpenAI 相容 API 的 +AI 聊天助手。AI 面板讓您可以直接在編輯器內與大型語言模型對話。 + +設定 +----- + +使用 AI 助手前，您需要先進行設定： + +1. 從選單開啟 AI 設定對話框 +2. 設定以下參數： + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 設定項目 + - 說明 + * - **API Base URL** + - API 端點（例如 ``https://api.openai.com/v1``） + * - **API Key** + - 您的 OpenAI API 金鑰 + * - **Model** + - 使用的模型（例如 ``gpt-3.5-turbo``、``gpt-4`` 或任何自訂模型） + * - **System Prompt** + - 設定 AI 行為與上下文的範本 + +設定會儲存到 ``.jeditor/ai_config.json``，在不同工作階段之間持續保留。 + +您也可以透過環境變數設定 API 金鑰。 + +聊天介面 +--------- + +AI 聊天面板提供： + +- **訊息歷史** — 可捲動的聊天歷史，包含所有先前的訊息 +- **輸入欄位** — 在面板底部輸入提示詞 +- **字型大小調整** — 自訂聊天面板的字型大小 +- **唯讀訊息區域** — 聊天歷史以唯讀方式顯示 + +非同步通訊 +----------- + +AI 請求以非同步方式處理，保持編輯器的回應能力： + +- 訊息在背景執行緒中傳送給 AI +- 回應透過可設定的計時器間隔拉取回來 +- 訊息佇列確保有序通訊 +- 等待回應期間 UI 保持完全互動 + +錯誤處理 +--------- + +如果 AI 請求失敗（例如網路錯誤、無效的 API 金鑰），JEditor 會顯示清楚的錯誤對話框 +描述問題。解決問題後，聊天工作階段可繼續正常使用。 diff --git a/docs/source/docs/Zh/api_reference.rst b/docs/source/docs/Zh/api_reference.rst new file mode 100644 index 0000000..58e8a96 --- /dev/null +++ b/docs/source/docs/Zh/api_reference.rst @@ -0,0 +1,258 @@ +API 參考 +========= + +JEditor 提供公開的 Python API，讓您可以將它作為函式庫使用、擴充功能， +或整合到您自己的應用程式中。 + +啟動編輯器 +----------- + +.. code-block:: python + + from je_editor import start_editor + + start_editor() + +以程式方式啟動完整的 JEditor 應用程式。 + +核心類別 +--------- + +EditorMain +^^^^^^^^^^^ + +主視窗類別，包含整個編輯器 UI。 + +.. code-block:: python + + from je_editor import EditorMain + +EditorWidget +^^^^^^^^^^^^^ + +程式碼編輯器元件（單一編輯分頁）— 自訂的 ``QPlainTextEdit``。 + +.. code-block:: python + + from je_editor import EditorWidget + +FullEditorWidget +^^^^^^^^^^^^^^^^^ + +完整的編輯器元件，包含行號、語法高亮和輸出顯示， +適合嵌入到停靠面板中。 + +.. code-block:: python + + from je_editor import FullEditorWidget + +MainBrowserWidget +^^^^^^^^^^^^^^^^^^ + +嵌入式網頁瀏覽器元件。 + +.. code-block:: python + + from je_editor import MainBrowserWidget + +使用自訂分頁擴充編輯器 +------------------------ + +使用 ``EDITOR_EXTEND_TAB`` 為 JEditor 新增自訂分頁： + +.. code-block:: python + + from je_editor import start_editor, EDITOR_EXTEND_TAB + + EDITOR_EXTEND_TAB.update({"My Tab": MyCustomWidget}) + + start_editor() + +詳見 :doc:`how_to_extend_using_pyside` 的完整範例。 + +程序管理器 +----------- + +ExecManager +^^^^^^^^^^^^ + +管理程式執行（執行 Python 腳本和編譯後的二進位檔）。 + +.. code-block:: python + + from je_editor import ExecManager + +ShellManager +^^^^^^^^^^^^^ + +管理 Shell 命令執行。 + +.. code-block:: python + + from je_editor import ShellManager + +語法高亮 +--------- + +PythonHighlighter +^^^^^^^^^^^^^^^^^^ + +內建的 Python 語法高亮器。 + +.. code-block:: python + + from je_editor import PythonHighlighter + +syntax_extend_setting_dict / syntax_rule_setting_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +定義高亮器語法關鍵字和規則的字典。 + +.. code-block:: python + + from je_editor import syntax_extend_setting_dict, syntax_rule_setting_dict + +設定 +----- + +user_setting_dict +^^^^^^^^^^^^^^^^^^ + +包含所有使用者設定（字型、語言、主題等）的字典。 + +.. code-block:: python + + from je_editor import user_setting_dict + +user_setting_color_dict +^^^^^^^^^^^^^^^^^^^^^^^^ + +包含所有色彩設定的字典。 + +.. code-block:: python + + from je_editor import user_setting_color_dict + +多語言 +------- + +language_wrapper +^^^^^^^^^^^^^^^^^ + +根據目前語言返回指定鍵值的翻譯字串。 + +.. code-block:: python + + from je_editor import language_wrapper + + label = language_wrapper("file_menu_label") # 返回 "File" 或對應的翻譯 + +english_word_dict / traditional_chinese_word_dict +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +內建的翻譯字典。 + +.. code-block:: python + + from je_editor import english_word_dict, traditional_chinese_word_dict + +插件 API +--------- + +程式語言插件 +^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_programming_language, + get_programming_language_plugin, + get_all_programming_language_suffixes, + ) + +- ``register_programming_language(suffix, syntax_words, syntax_rules=None)`` — 註冊新語言 +- ``get_programming_language_plugin(suffix)`` — 取得特定副檔名的插件 +- ``get_all_programming_language_suffixes()`` — 列出所有已註冊的副檔名 + +自然語言插件 +^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_natural_language, + get_natural_language_plugin, + get_all_natural_languages, + ) + +- ``register_natural_language(language_key, display_name, word_dict)`` — 註冊翻譯 +- ``get_natural_language_plugin(language_key)`` — 取得翻譯字典 +- ``get_all_natural_languages()`` — 列出所有已註冊的語言 + +執行設定插件 +^^^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_plugin_run_config, + get_all_plugin_run_configs, + get_plugin_run_config_by_suffix, + ) + +- ``register_plugin_run_config(config)`` — 註冊執行���定 +- ``get_all_plugin_run_configs()`` — 列出所有執行設定 +- ``get_plugin_run_config_by_suffix(suffix)`` — ��得特定副檔名的執行設定 + +插件元資料 +^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import ( + register_plugin_metadata, + get_all_plugin_metadata, + ) + +- ``register_plugin_metadata(name, author, version)`` — 註冊插件資訊 +- ``get_all_plugin_metadata()`` — 列出所有已註冊的插件元資料 + +插件載入器 +^^^^^^^^^^^ + +.. code-block:: python + + from je_editor import load_external_plugins + + load_external_plugins() + +掃描 ``jeditor_plugins/`` 資料夾並載入所有發現的插件。 + +日誌 +----- + +.. code-block:: python + + from je_editor import jeditor_logger + + jeditor_logger.info("自訂日誌訊息") + +``jeditor_logger`` 是標準的 Python 日誌器，寫入 ``JEditor.log``。 + +例外處理 +--------- + +JEditor 定義了一套自訂例外類別階層： + +.. code-block:: python + + from je_editor import ( + JEditorException, # 基礎例外 + JEditorExecException, # 執行錯誤 + JEditorRunOnShellException, # Shell 執行錯誤 + JEditorSaveFileException, # 檔案儲存錯誤 + JEditorOpenFileException, # 檔案開啟錯誤 + JEditorContentFileException, # 檔案��容錯誤 + JEditorCantFindLanguageException, # 找不到語言 + JEditorJsonException, # JSON 解析錯誤 + ) diff --git a/docs/source/docs/Zh/browser.rst b/docs/source/docs/Zh/browser.rst new file mode 100644 index 0000000..1782e96 --- /dev/null +++ b/docs/source/docs/Zh/browser.rst @@ -0,0 +1,51 @@ +內建瀏覽器 +=========== + +JEditor 內建嵌入式網頁瀏覽器，讓您可以瀏覽文件、搜尋網頁和檢視網頁內容， +全程無需離開編輯器。 + +導覽功能 +--------- + +瀏覽器提供完整的導覽工具列： + +- **URL / 搜尋列** — 直接輸入 URL 或搜尋關鍵字 +- **上一頁 / 下一頁** — 在瀏覽歷史中導覽 +- **重新整理** — 重新載入目前頁面 +- **停止** — 取消載入目前頁面 + +搜尋 +----- + +**頁面內搜尋：** + +- 按下 ``Ctrl+F`` 開啟頁面內文字搜尋 +- 在目前的網頁中尋找文字 + +**網頁搜尋：** + +- 在網址列輸入搜尋關鍵字（非 URL） +- JEditor 會使用設定的搜尋引擎（預設為 Google）進行搜尋 + +瀏覽器分頁 +----------- + +您可以開啟多個瀏覽器實例： + +- **Tab 選單** — 新增瀏覽器分頁（WEB Tab） +- **Dock 選單** — 以可停靠面板的方式開啟瀏覽器 +- **Stack Overflow 分頁** — 直接開啟 Stack Overflow 的專用分頁 + +下載追蹤 +--------- + +瀏覽器包含下載追蹤視窗，顯示檔案下載的進度。 + +功能特色 +--------- + +- 完整的網頁瀏覽功能 +- JavaScript 支援（透過 WebKit/WebEngine） +- 連結導覽與點擊處理 +- 與編輯器的分頁和停靠系統整合 +- 可自訂搜尋引擎前綴 diff --git a/docs/source/docs/Zh/code_execution.rst b/docs/source/docs/Zh/code_execution.rst new file mode 100644 index 0000000..cf964fb --- /dev/null +++ b/docs/source/docs/Zh/code_execution.rst @@ -0,0 +1,103 @@ +程式執行與除錯 +================ + +JEditor 內建程式碼執行引擎，支援執行 Python 腳本、編譯式語言和任意 Shell 命令， +無需離開編輯器。 + +執行 Python 腳本 +------------------ + +按下 **F5** 執行目前的 Python 檔案。JEditor 會： + +1. 偵測 Python 直譯器（如有虛擬環境則自動使用） +2. 在背景程序中執行腳本 +3. 即時串流輸出到結果面板 +4. 以紅色顯示錯誤訊息，方便識別 + +**虛擬環境支援：** + +JEditor 會自動偵測專案根目錄中的 ``venv`` 資料夾，並使用虛擬環境的 Python 直譯器執行， +確保套件解析正確。 + +您也可以從 **Python Env** 選單手動選擇 Python 直譯器。 + +除錯模式 +--------- + +按下 **F9** 以除錯模式啟動目前的 Python 檔案： + +- 整合 Python 除錯器（pdb） +- 執行期間檢視變數（詳見下方「變數檢視器」） +- 支援逐步除錯 + +停止執行 +^^^^^^^^^ + +- **Shift+F5** — 停止所有正在執行的程序 +- 也可從 **Run** 選單停止個別程序 + +執行其他語言 +-------------- + +透過插件系統，JEditor 支援執行其他語言的檔案： + +**直譯式語言**（直接執行）： + +- **Go** — ``go run file.go`` +- **Java** — ``java file.java`` + +**編譯式語言**（先編譯再執行）： + +- **C** — ``gcc file.c -o file && ./file`` +- **C++** — ``g++ file.cpp -o file && ./file`` +- **Rust** — ``rustc file.rs -o file && ./file`` + +詳情請參閱 :doc:`plugins` 了解如何為新語言新增執行設定。 + +Shell 命令執行 +---------------- + +JEditor 提供內建的 Shell 用於執行任意命令： + +- 直接執行任何 Shell / 終端機命令 +- 跨平台 Shell 支援：``cmd``、``PowerShell``、``bash``、``sh`` +- 從主控台元件的下拉選單選擇偏好的 Shell +- 即時串流輸出，結果以顏色區分 +- 隨時可停止正在執行的 Shell 程序 + +輸出顯示 +--------- + +編輯器底部的結果面板顯示執行輸出： + +- **正常輸出** — 以設定的正常顏色顯示 +- **錯誤輸出** — 以紅色顯示，方便識別 +- **系統訊息** — 以特定顏色顯示 +- 輸出行數上限可設定（預設：200,000 行）以防止記憶體問題 +- 可從 **Run** 選單或主控台的清除按鈕清除結果 + +變數檢視器 +----------- + +變數檢視器提供執行期間的變數除錯功能，以表格形式呈現： + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 欄位 + - 說明 + * - 名稱 + - 變數名稱 + * - 型別 + - 變數的 Python 型別 + * - 值 + - 目前的值（可編輯） + +功能特色： + +- 腳本執行期間即時檢視變數 +- 過濾內建變數（以 ``__`` 開頭的變數） +- 可編輯變數值，支援基於 AST 的型別轉換 +- 動態更新命名空間 +- 排序與搜尋功能 diff --git a/docs/source/docs/Zh/code_quality.rst b/docs/source/docs/Zh/code_quality.rst new file mode 100644 index 0000000..d292eb6 --- /dev/null +++ b/docs/source/docs/Zh/code_quality.rst @@ -0,0 +1,47 @@ +程式碼品質與格式化 +==================== + +JEditor 整合了多種程式碼品質工具，幫助您撰寫乾淨、一致的程式碼。 + +YAPF Python 格式化 +-------------------- + +`YAPF `_（Yet Another Python Formatter）將 Python 程式碼 +重新格式化為符合 Google 風格指南的格式。 + +- **快捷鍵：** ``Ctrl+Shift+Y`` +- 格式化整個檔案 +- 套用一致的縮排、間距和換行 +- 可從 **Check Code Style** 選單使用 + +PEP 8 檢查 +------------ + +JEditor 整合了 `pycodestyle `_ 進行 PEP 8 合規檢查。 + +- **快捷鍵：** ``Ctrl+Alt+P`` +- 報告違規項目，包含行號與偏移量 +- 可自訂檢查項目（預設過濾 W191 Tab 警告） +- 可從 **Check Code Style** 選單使用 + +Ruff 靜態分析 +--------------- + +`Ruff `_ 是速度極快的 Python 靜態分析工具， +在背景自動執行： + +- 透過 ``watchdog`` 監控檔案系統變更 +- 在背景執行緒中進行分析，保持 UI 流暢 +- 防抖機制避免快速編輯時過度執行 +- 涵蓋數百條 Python 檢查規則 +- 結果回報不會阻塞您的工作流程 + +JSON 格式化 +------------- + +JEditor 可以格式化與驗證 JSON 檔案： + +- **快捷鍵：** ``Ctrl+J`` +- 以適當的縮排美化顯示 JSON +- 驗證 JSON 語法並回報錯誤 +- 可從 **Check Code Style** 選單使用 diff --git a/docs/source/docs/Zh/configuration.rst b/docs/source/docs/Zh/configuration.rst new file mode 100644 index 0000000..8c5514c --- /dev/null +++ b/docs/source/docs/Zh/configuration.rst @@ -0,0 +1,152 @@ +設定與配置 +=========== + +JEditor 將所有使用者設定儲存在目前工作目錄下的 ``.jeditor/`` 資料夾中。 +設定會在首次啟動時自動建立，並在不同工作階段之間持續保留。 + +設定檔案 +--------- + +user_setting.json +^^^^^^^^^^^^^^^^^^ + +主要設定檔控制編輯器的行為與外觀： + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 設定項目 + - 說明 + * - ``ui_font_family`` + - 主 UI 的字型系列（選單、面板、對話框） + * - ``ui_font_size`` + - 主 UI 的字型大小 + * - ``editor_font_family`` + - 程式碼編輯器的字型系列 + * - ``editor_font_size`` + - 程式碼編輯器的字型大小 + * - ``language`` + - UI 語言（``English``、``Traditional Chinese`` 或插件提供的語言） + * - ``theme`` + - UI 主題風格（深色或淺色 Material 主題） + * - ``encoding`` + - 預設檔案編碼（``UTF-8``、``GBK``、``Latin-1``） + * - ``last_open_file`` + - 上次開啟的檔案路徑（啟動時恢復） + * - ``python_compiler`` + - 用於程式碼執行的 Python 直譯器路徑 + * - ``max_output_lines`` + - 輸出面板的最大行數（預設：200,000） + * - ``recent_files`` + - 最近開啟的檔案清單 + * - ``indent_size`` + - 縮排大小（空格數，預設：4） + +user_color_setting.json +^^^^^^^^^^^^^^^^^^^^^^^^ + +控制編輯器與輸出的色彩配置： + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 設定項目 + - 說明 + * - ``line_number_color`` + - 行號文字的 RGB 顏色 + * - ``line_number_bg_color`` + - 行號區域背景的 RGB 顏色 + * - ``current_line_color`` + - 目前行高亮的 RGB 顏色 + * - ``normal_output_color`` + - 正常輸出文字的 RGB 顏色 + * - ``error_output_color`` + - 錯誤輸出文字的 RGB 顏色 + * - ``warning_output_color`` + - 警告輸出文字的 RGB 顏色 + +所有顏色以 RGB 陣列指定，例如 ``[255, 0, 0]`` 代表紅色。 + +ai_config.json +^^^^^^^^^^^^^^^ + +AI 助手設定（詳見 :doc:`ai_assistant`）： + +- API Base URL +- API 金鑰 +- 模型名稱 +- 系統提示詞範本 + +主題 +----- + +JEditor 透過 `qt-material `_ 支援深色和淺色主題： + +- **預設：** Dark Amber 主題 +- 從 **UI Style** 選單切換主題 +- 主題變更可能需要重新啟動應用程式才能完全生效 + +字型自訂 +--------- + +JEditor 為 UI 和程式碼編輯器提供獨立的字型設定： + +**UI 字型：** +- 從 **File** 選單變更 +- 影響選單、面板、對話框和按鈕 +- 字型系列和大小可獨立設定 + +**編輯器字型：** +- 從 **Text** 選單變更 +- 僅影響程式碼編輯區域 +- 字型系列和大小可獨立設定 +- 變更立即生效 + +可停靠面板 +----------- + +JEditor 的 UI 採用 Qt 的停靠元件系統，面板可重新排列： + +- **編輯器** — 主要的程式碼編輯區域 +- **輸出** — 程式碼執行結果 +- **檔案樹** — 專案目錄瀏覽器 +- **主控台** — Shell / IPython 主控台 +- **AI 聊天** — AI 助手面板 +- **Git** — Git 客戶端面板 +- **瀏覽器** — 內建網頁瀏覽器 +- **變數檢視器** — 執行期間的變數除錯 + +所有面板都可以： + +- 拖曳到視窗內的不同位置 +- 浮動為獨立視窗 +- 在同一停靠區域內堆疊為分頁 +- 從 **Dock** 選單隱藏或恢復 + +系統匣 +------- + +JEditor 支援系統匣整合： + +- 最小化到系統匣而非關閉 +- 系統匣圖示可快速恢復視窗 +- 最小化時繼續在背景運行 + +多語言 UI +---------- + +JEditor 支援多種 UI 語言： + +**內建語言：** + +- English（預設） +- 繁體中文 + +**透過插件新增語言：** + +可透過插件系統新增額外語言（詳見 :doc:`plugins`）。 +語言變更在重新啟動應用程式後生效。 + +從 **Language** 選單切換語言。 diff --git a/docs/source/docs/Zh/console.rst b/docs/source/docs/Zh/console.rst new file mode 100644 index 0000000..6452d8e --- /dev/null +++ b/docs/source/docs/Zh/console.rst @@ -0,0 +1,46 @@ +主控台與 REPL +=============== + +JEditor 提供兩種互動式主控台：用於執行系統命令的 Shell 主控台， +以及用於互動式 Python 工作階段的 Jupyter/IPython 主控台。 + +Shell 主控台 +-------------- + +內建的 Shell 主控台讓您無需離開編輯器即可執行系統命令。 + +**功能特色：** + +- 直接執行任何 Shell 命令 +- **命令歷史** — 使用 **上/下** 方向鍵瀏覽先前的命令 +- **顏色標示輸出：** + - 正常輸出以預設顏色顯示 + - 錯誤輸出以紅色顯示 + - 系統訊息以特定顏色顯示 +- **工作目錄** — 選擇並顯示目前的工作目錄 +- **Shell 選擇** — 可選擇：``auto``、``cmd``、``PowerShell``、``bash``、``sh`` +- **控制按鈕：** 執行、停止、清除 +- 輸出限制為 10,000 行以防止記憶體問題 +- 等寬字型（Consolas 或系統預設） + +**Shell 選擇器：** + +使用主控台元件頂部的下拉選單選擇要使用的 Shell。 +``auto`` 選項會選擇平台預設值（Windows 為 ``cmd``，Linux/macOS 為 ``bash``）。 + +Jupyter / IPython 主控台 +-------------------------- + +JEditor 包含基於 ``qtconsole`` 的嵌入式 Jupyter/IPython 主控台： + +- 完整的行程內 IPython 核心 +- 豐富的互動式 Python 環境 +- Tab 自動補全與語法高亮 +- Magic 命令（``%timeit``、``%run`` 等） +- Qt 事件迴圈整合，無縫 GUI 互動 +- 編輯器關閉時正確清理資源 + +**使用方式：** + +從 **Tab** 或 **Dock** 選單開啟 IPython 主控台。您將獲得一個功能完整的 +IPython 工作階段，可存取環境中所有已安裝的套件。 diff --git a/docs/source/docs/Zh/editor.rst b/docs/source/docs/Zh/editor.rst new file mode 100644 index 0000000..1689220 --- /dev/null +++ b/docs/source/docs/Zh/editor.rst @@ -0,0 +1,146 @@ +程式碼編輯器 +============= + +JEditor 的核心是一個功能強大的多分頁程式碼編輯器，基於 Qt 的 ``QPlainTextEdit`` 打造， +專為速度、靈活性和流暢的開發體驗而設計。 + +多分頁編輯 +----------- + +透過分頁式介面同時處理多個檔案： + +- 在不同分頁中開啟多個檔案 +- 點擊分頁即可切換 +- 可個別關閉分頁 +- 支援從檔案系統拖曳檔案到編輯器 +- 自動追蹤目前檔案路徑與分頁狀態 + +檔案操作 +--------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 操作 + - 說明 + * - **新建檔案** (``Ctrl+N``) + - 建立一個新的空白檔案 + * - **開啟檔案** (``Ctrl+O``) + - 開啟現有檔案並載入到分頁中 + * - **開啟資料夾** (``Ctrl+K``) + - 開啟專案資料夾並在檔案樹中顯示 + * - **儲存檔案** (``Ctrl+S``) + - 將目前分頁的內容儲存到磁碟 + +最近開啟的檔案 +^^^^^^^^^^^^^^^ + +JEditor 會記錄最近開啟的檔案清單，可從 **File** 選單快速存取。 + +自動儲存 +^^^^^^^^^ + +JEditor 內建自動儲存功能，定期儲存您的工作： + +- 每個開啟的檔案都有獨立的背景執行緒負責儲存 +- 可設定儲存間隔時間 +- 偵測外部檔案變更並處理衝突 +- 追蹤檔案修改狀態 + +語法高亮 +--------- + +JEditor 內建 Python 語法高亮，並透過插件系統支援其他程式語言。 + +**內建 Python 高亮** 包括： + +- 關鍵字（``if``、``else``、``for``、``while``、``def``、``class`` 等） +- 內建函式（``print``、``len``、``range`` 等） +- 字串（單行與多行） +- 註解 +- 裝飾器 +- 數字 +- 可透過色彩設定自訂顏色 + +**透過插件支援更多語言：** + +可透過插件系統新增額外的語言支援。預先提供的插件包括： + +- C（``.c``） +- C++（``.cpp``、``.cxx``、``.cc``、``.h``、``.hpp``、``.hxx``） +- Go（``.go``） +- Java（``.java``） +- Rust（``.rs``） + +詳情請參閱 :doc:`plugins`。 + +自動補全 +--------- + +JEditor 整合了 `Jedi `_ 提供智慧型 Python 程式碼補全： + +- 根據目前程式碼提供上下文感知建議 +- 支援虛擬環境（venv）以獲得準確的套件補全 +- 在背景執行緒中運行，UI 始終保持回應 +- 可設定大小寫敏感度與補全行為 + +行號顯示 +--------- + +編輯器在左側的行號區域顯示行號： + +- 行號隨文件變更動態更新 +- 可自訂行號文字與背景顏色 +- 目前行號會以高亮方式顯示，方便快速識別 + +目前行高亮 +----------- + +游標所在行會以特殊背景色高亮顯示，方便識別目前的編輯位置。 +高亮顏色可透過色彩設定自訂。 + +檔案樹 +-------- + +開啟資料夾（``Ctrl+K``）後，JEditor 會在左側顯示檔案樹： + +- 瀏覽專案的完整目錄結構 +- 點擊任意檔案即可在新分頁中開啟 +- 支援展開與收合目錄 +- 大型專案可捲動瀏覽 + +編碼支援 +--------- + +JEditor 支援多種檔案編碼： + +- **UTF-8**（預設） +- **GBK** +- **Latin-1** +- 開啟檔案時自動偵測編碼 +- 可從 **File > Encoding** 選單為個別檔案選擇編碼 +- 儲存時保留檔案原有編碼 + +搜尋與取代 +----------- + +JEditor 提供強大的搜尋與取代功能： + +**檔案內搜尋：** + +- 在目前檔案內搜尋 +- 區分大小寫與不區分大小寫選項 +- 支援正規表達式（regex） + +**全專案搜尋：** + +- 跨已開啟資料夾中所有檔案搜尋 +- 結果以表格顯示，包含檔案路徑與行號 +- 點擊結果即可直接跳轉到匹配位置 +- 在背景執行緒中運行，適用於大型程式碼庫 + +**取代：** + +- 取代單一匹配或一次取代全部 +- 支援與搜尋相同的選項（大小寫、正規表達式） diff --git a/docs/source/docs/Zh/getting_started.rst b/docs/source/docs/Zh/getting_started.rst new file mode 100644 index 0000000..8d14adb --- /dev/null +++ b/docs/source/docs/Zh/getting_started.rst @@ -0,0 +1,103 @@ +快速入門 +========= + +系統需求 +--------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 平台 + - 版本 + * - Windows + - Windows 10 / 11 + * - macOS + - 10.5 ~ 11 Big Sur + * - Linux + - Ubuntu 20.04+ + * - Raspberry Pi + - 3B+ + * - Python + - 3.10、3.11、3.12 + +安裝方式 +--------- + +**從 PyPI 安裝：** + +.. code-block:: bash + + pip install je_editor + +**從原始碼安裝：** + +.. code-block:: bash + + git clone https://github.com/JE-Chen/je_editor.git + cd je_editor + pip install . + +依賴套件 +^^^^^^^^^ + +JEditor 會自動安裝以下依賴套件： + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - 套件 + - 用途 + * - PySide6 + - GUI 框架（Qt for Python） + * - qt-material + - 深色 / 淺色 Material 主題 + * - yapf + - Python 程式碼格式化 + * - jedi + - Python 自動補全 + * - ruff + - 快速 Python 靜態分析工具 + * - gitpython + - Git 操作 + * - langchain / langchain_openai + - AI 助手（LLM 整合） + * - watchdog + - 檔案系統監控 + * - pycodestyle + - PEP 8 檢查 + * - qtconsole + - Jupyter / IPython 主控台元件 + * - frontengine + - 額外 UI 元件 + +啟動 JEditor +-------------- + +**從命令列啟動：** + +.. code-block:: bash + + python -m je_editor + +**作為 Python 函式庫使用：** + +.. code-block:: python + + from je_editor import start_editor + + start_editor() + +啟動後，JEditor 預設以深色主題開啟。您可以隨時從 **UI Style** 選單更換主題。 + +專案結構 +--------- + +JEditor 啟動時會在目前工作目錄下建立 ``.jeditor/`` 資料夾，用於儲存： + +- ``user_setting.json`` — UI 偏好設定、字型、語言、最近開啟的檔案 +- ``user_color_setting.json`` — 編輯器與輸出的色彩配置 +- ``ai_config.json`` — AI 助手設定（如有啟用） + +這些檔案會在首次啟動時自動建立。 diff --git a/docs/source/docs/Zh/git_integration.rst b/docs/source/docs/Zh/git_integration.rst new file mode 100644 index 0000000..0e205af --- /dev/null +++ b/docs/source/docs/Zh/git_integration.rst @@ -0,0 +1,92 @@ +Git 整合 +========= + +JEditor 內建完整功能的 Git 客戶端與圖形介面，由 +`GitPython `_ 驅動。所有 Git 操作都可直接在 +編輯器內完成，無需外部工具。 + +開啟儲存庫 +----------- + +從 Git 面板開啟 Git 儲存庫。JEditor 會： + +- 自動偵測儲存庫根目錄 +- 在工具列顯示目前分支 +- 載入提交歷史 +- 下次啟動時恢復上次開啟的儲存庫 + +分支管理 +--------- + +直接在編輯器內管理分支： + +- **列出所有分支** — 在分支樹中檢視本地與遠端分支 +- **切換分支** — 從工具列的下拉選單簽出任意分支 +- **分支選擇器** — 透過工具列下拉選單快速切換分支 + +提交歷史 +--------- + +在可排序的表格中檢視完整的提交歷史： + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - 欄位 + - 說明 + * - SHA + - 提交雜湊值（縮寫） + * - 作者 + - 提交者 + * - 日期 + - 提交日期與時間 + * - 訊息 + - 提交訊息 + +**提交圖表：** + +JEditor 可以顯示視覺化的提交圖表，展示分支關係和合併歷史， +幫助您了解專案的開發時間線。 + +差異檢視器 +----------- + +JEditor 提供強大的並排差異檢視器： + +- **顏色標示變更** — 新增、刪除和修改的行以不同顏色標示 +- **行號** — 舊版本與新版本都顯示行號 +- **多檔案差異** — 在同一次檢視中查看多個檔案的變更 +- **唯讀顯示** — 差異檢視為唯讀模式，防止意外修改 + +暫存與提交 +----------- + +在編輯器內執行完整的 Git 工作流程： + +1. **暫存變更** — 選擇個別檔案進行暫存 +2. **取消暫存** — 將檔案從暫存區移除 +3. **撰寫提交訊息** — 輸入描述性的提交訊息 +4. **提交** — 以暫存的變更建立新的提交 + +遠端操作 +--------- + +與遠端儲存庫互動： + +- **推送（Push）** — 將本地提交推送到遠端儲存庫 +- **拉取（Pull）** — 從遠端拉取最新變更 +- **遠端管理** — 設定遠端儲存庫 URL +- **追蹤分支偵測** — 自動偵測上游分支 + +稽核日誌 +--------- + +所有 Git 操作都會記錄到 ``audit.log`` 以供追蹤： + +- **時間戳** — 操作發生的時間 +- **動作** — 執行了什麼 Git 命令 +- **狀態** — 成功或失敗 +- **錯誤詳情** — 如果操作失敗，會記錄錯誤訊息 + +稽核日誌不會干擾 UI，即使記錄失敗也不會中斷操作。 diff --git a/docs/source/docs/Zh/how_to_extend_using_pyside.rst b/docs/source/docs/Zh/how_to_extend_using_pyside.rst index 15c3914..a5034a2 100644 --- a/docs/source/docs/Zh/how_to_extend_using_pyside.rst +++ b/docs/source/docs/Zh/how_to_extend_using_pyside.rst @@ -1,35 +1,80 @@ -如何用 Pyside 擴充 ----- +使用 PySide6 擴充 +=================== + +JEditor 基於 PySide6（Qt for Python）打造，您可以透過自訂的 Qt 元件 +新增分頁或停靠面板來擴充編輯器。 + +新增自訂分頁 +-------------- + +使用 ``EDITOR_EXTEND_TAB`` 字典將自訂元件註冊為編輯器中的新分頁。 +鍵值為分頁名稱，值為元件類別（非實例）。 + +**範例：** .. code-block:: python - from PySide6.QtWidgets import QWidget, QGridLayout, QLineEdit, QPushButton, QLabel + from PySide6.QtWidgets import QWidget, QGridLayout, QLineEdit, QPushButton, QLabel + from je_editor import start_editor, EDITOR_EXTEND_TAB + + + class TestUI(QWidget): + """一個簡單的自訂元件，包含文字輸入欄和提交按鈕。""" + + def __init__(self): + super().__init__() + self.grid_layout = QGridLayout(self) + self.grid_layout.setContentsMargins(0, 0, 0, 0) + + self.label = QLabel("") + self.line_edit = QLineEdit() + self.submit_button = QPushButton("Submit") + self.submit_button.clicked.connect(self.show_input_text) - from je_editor import start_editor, EDITOR_EXTEND_TAB + self.grid_layout.addWidget(self.label, 0, 0) + self.grid_layout.addWidget(self.line_edit, 1, 0) + self.grid_layout.addWidget(self.submit_button, 2, 0) + def show_input_text(self): + self.label.setText(self.line_edit.text()) - # You can use you own QWidget - class TestUI(QWidget): - def __init__(self): - super().__init__() - self.grid_layout = QGridLayout(self) - self.grid_layout.setContentsMargins(0, 0, 0, 0) - self.grid_layout.setContentsMargins(0, 0, 0, 0) - self.label = QLabel("") - self.line_edit = QLineEdit() - self.submit_button = QPushButton("Submit") - self.submit_button.clicked.connect(self.show_input_text) - self.grid_layout.addWidget(self.label, 0, 0) - self.grid_layout.addWidget(self.line_edit, 1, 0) - self.grid_layout.addWidget(self.submit_button, 2, 0) + # 註冊自訂分頁：{"分頁名稱": 元件類別} + EDITOR_EXTEND_TAB.update({"test": TestUI}) - def show_input_text(self): - self.label.setText(self.line_edit.text()) + # 啟動帶有自訂分頁的編輯器 + start_editor() - # tab name: tab instance(QWidget) - EDITOR_EXTEND_TAB.update({"test": TestUI}) +執行此腳本後，JEditor 將在預設分頁旁邊新增一個 "test" ���頁。 + +運作原理 +^^^^^^^^^ + +1. ``EDITOR_EXTEND_TAB`` 是一個將分頁名稱對應到元件類別的字典 +2. JEditor 在建構 UI 時會建立每個已註冊元件類別的實例 +3. 元件會作為新分頁加入到分頁列 +4. 您的元件可完整使用 PySide6/Qt 的功能 + +提示 +^^^^^ + +- 您的元件類別必須繼承自 ``QWidget``（或其子類別） +- 使用佈局（``QGridLayout``、``QVBoxLayout`` 等）實現響應式設計 +- 您可以透過公開 API 存取 JEditor 的內部元件 +- 可以多次呼叫 ``update()`` 或傳入包含多個項目的字典來註冊多個自訂分頁 + +使用 JEditor 元件 +------------------- + +您也可以在自己的 PySide6 應用程式中使用 JEditor 的個別元件： + +.. code-block:: python - start_editor() + from je_editor import EditorWidget, MainBrowserWidget, FullEditorWidget +- ``EditorWidget`` — 獨立的程式碼編輯器元件 +- ``FullEditorWidget`` — 完整的編輯器，包含行號和輸出面板 +- ``MainBrowserWidget`` — 獨立的網頁瀏覽器元件 +這些元件可以加入任何 PySide6 佈局，方便將程式碼編輯或瀏覽功能 +整合到您自己的應用程式中。 diff --git a/docs/source/docs/Zh/how_to_use.rst b/docs/source/docs/Zh/how_to_use.rst deleted file mode 100644 index b6ff233..0000000 --- a/docs/source/docs/Zh/how_to_use.rst +++ /dev/null @@ -1,60 +0,0 @@ -如何使用 ----- - -* 現代編輯器。 -* 舊版 JEditor 重製。 -* 自動保存，Encoding 功能。 -* 多程式同時運行和 shell 運行器。 -* 包含 yapf python 格式檢查器。 -* 包含重新格式化 JSON。 -* 虛擬環境支持。 -* 暗色和亮色模式 UI 支持。 -* 文件樹支持。 -* 程式碼行數顯示。 -* 當前行高亮顯示。 -* Python 程式碼高亮顯示。 -* 比舊版 JEditor 效率高 1000%。 -* 獨立於作業系統。 -* JEditor 默認使用如下所示的深色界面： -.. image:: image/JEditor.png -* File 選單 - * New File (建立一個檔案但不切換到該檔案) - * Open File（打開檔案並將內容讀取到程式編輯區內容） - * Save File (將當前程式編輯區內容保存到檔案) - * Font (選擇主 UI 字體) - * Font Size (選擇主 UI 字體大小) - * Encoding (選擇程式運行器和 shell 運行器 Encoding) -* Run 選單 - * Run Program (使用程式運行器運行程式編輯區內容) - * Run On Shell (使用 shell 運行程式編輯區內容) - * Clean Result (清除程式或 shell 結果) - * Stop Program (停止程式運行器) - * Run Help 選單 - * Run Help (運行幫助訊息) - * Shell Help (Shell 幫助訊息) -* Text 選單 - * Font (選擇編輯器默認字體) - * Font Size (更改編輯器默認字體大小) -* Check Code Style 選單 - * yapf (使用 yapf 檢查 Python 代碼風格) - * Reformat JSON (重新格式化並驗證 JSON) -* Help 選單 - * GitHub (打開 JEditor GitHub) - * Doc (打開 JEditor 文件) - * About (關於 JEditor 信息) -* Python Env 選單 - * Create Venv (嘗試使用 shell 運行器創建 venv) - * pip upgrade package (嘗試使用 shell 運行器安裝與升級套件) - * pip package (嘗試使用 shell 運行器安裝套件) - * choose python interpreter (選擇所要使用的直譯器) -* Tab 選單 - * Add Editor Tab (開啟 Editor 分頁) - * Add FrontEngine Tab (開啟 FrontEngine 分頁) - * Add WEB Tab (開啟 browser 分頁) - * Add Stackoverflow Tab (開啟 Stackoverflow 分頁) -* Dock 選單 - * New Dock Browser (開啟 Browser 區域) - * New Dock Stackoverflow (開啟 Stackoverflow 區域) - * New Dock Editor (開啟 Editor 區域) - * New Dock FrontEngine (開啟 FrontEngine 區域) -* UI Style Menu（包括許多用戶可以使用的 UI） diff --git a/docs/source/docs/Zh/keyboard_shortcuts.rst b/docs/source/docs/Zh/keyboard_shortcuts.rst new file mode 100644 index 0000000..6eb0805 --- /dev/null +++ b/docs/source/docs/Zh/keyboard_shortcuts.rst @@ -0,0 +1,80 @@ +鍵盤快捷鍵 +============ + +JEditor 提供常用操作的鍵盤快捷鍵，讓您的工作流程更快速、更有效率。 + +檔案操作 +--------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 快捷鍵 + - 動作 + * - ``Ctrl+N`` + - 建立新檔案 + * - ``Ctrl+O`` + - 開啟現有檔案 + * - ``Ctrl+K`` + - 開啟資料夾（專案） + * - ``Ctrl+S`` + - 儲存目前檔案 + +程式碼執行 +----------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 快捷鍵 + - 動作 + * - ``F5`` + - 執行目前的 Python 檔案 + * - ``F9`` + - 以除錯模式執行目前的 Python 檔案 + * - ``Shift+F5`` + - 停止所有正在執行的程序 + +程式碼品質 +----------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 快捷鍵 + - 動作 + * - ``Ctrl+Shift+Y`` + - 使用 YAPF 格式化 Python 程式碼 + * - ``Ctrl+Alt+P`` + - 檢查 PEP 8 合規性 + * - ``Ctrl+J`` + - 格式化 / 驗證 JSON + +瀏覽器 +------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 快捷鍵 + - 動作 + * - ``Ctrl+F`` + - 頁面內文字搜尋（瀏覽器） + +主控台 +------- + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - 快捷鍵 + - 動作 + * - ``上`` + - 上一個歷史命令 + * - ``下`` + - 下一個歷史命令 diff --git a/docs/source/docs/Zh/plugins.rst b/docs/source/docs/Zh/plugins.rst new file mode 100644 index 0000000..78be670 --- /dev/null +++ b/docs/source/docs/Zh/plugins.rst @@ -0,0 +1,336 @@ +插件系統 +========= + +JEditor 擁有完整的插件系統，讓您可以擴充編輯器，新增程式語言支援、 +UI 翻譯和自訂執行設定。 + +插件類型 +--------- + +JEditor 支援四種類型的插件： + +1. **程式語言插件** — 為新語言新增語法高亮 +2. **自然語言（翻譯）插件** — 新增 UI 翻譯 +3. **執行設定插件** — 定義如何執行特定類型的檔案 +4. **插件元資料** — 顯示在插件選單中的版本與作者資訊 + +插件目錄 +--------- + +插件會從工作目錄下的 ``jeditor_plugins/`` 資料夾自動發現： + +.. code-block:: text + + working_directory/ + jeditor_plugins/ + my_syntax.py # 單檔插件 + my_language.py + my_package/ # 套件插件 + __init__.py + +**發現規則：** + +- 以 ``_`` 或 ``.`` 開頭的檔案會被忽略 +- 每個插件 **必須** 定義一個 ``register()`` 函式 +- 套件插件使用 ``__init__.py`` 作為進入點 +- 重複的插件名稱以先找到的為準 + +插件元資料 +----------- + +每個插件可選擇性地定義元資料，顯示在 **Plugins** 選單中： + +.. code-block:: python + + PLUGIN_NAME = "My Plugin" # 顯示名稱 + PLUGIN_AUTHOR = "Your Name" # 作者 + PLUGIN_VERSION = "1.0.0" # 版本號 + +如未定義，則以檔名作為插件名稱。 + +程式語言插件 +------------- + +為任何程式語言新增語法高亮。 + +**API：** + +.. code-block:: python + + from je_editor.plugins import register_programming_language + + register_programming_language( + suffix=".ext", # 副檔名 + syntax_words={...}, # 關鍵字群組 + syntax_rules={...}, # 正規表達式規則（可選） + ) + +**syntax_words 格式：** + +定義關鍵字群組及其高亮顏色： + +.. code-block:: python + + from PySide6.QtGui import QColor + + syntax_words = { + "group_name": { + "words": ("keyword1", "keyword2", ...), + "color": QColor(r, g, b), + }, + # 更多群組... + } + +**syntax_rules 格式：** + +定義正規表達式模式，用於複雜的語法元素（註解、字串等）： + +.. code-block:: python + + syntax_rules = { + "rule_name": { + "rules": (r"regex_pattern", ...), + "color": QColor(r, g, b), + }, + } + +**完整範例 — Go 語法高亮：** + +.. code-block:: python + + """Go 語法高亮插件。""" + from PySide6.QtGui import QColor + from je_editor.plugins import register_programming_language + + PLUGIN_NAME = "Go Syntax Highlighting" + PLUGIN_AUTHOR = "Your Name" + PLUGIN_VERSION = "1.0.0" + + go_syntax_words = { + "keywords": { + "words": ( + "break", "case", "chan", "const", "continue", + "default", "defer", "else", "fallthrough", "for", + "func", "go", "goto", "if", "import", + "interface", "map", "package", "range", "return", + "select", "struct", "switch", "type", "var", + ), + "color": QColor(86, 156, 214), + }, + "types": { + "words": ( + "bool", "byte", "complex64", "complex128", + "float32", "float64", "int", "int8", "int16", + "int32", "int64", "rune", "string", "uint", + "uint8", "uint16", "uint32", "uint64", "uintptr", + "error", "nil", "true", "false", "iota", + ), + "color": QColor(78, 201, 176), + }, + } + + go_syntax_rules = { + "single_line_comment": { + "rules": (r"//[^\\n]*",), + "color": QColor(106, 153, 85), + }, + } + + + def register() -> None: + register_programming_language( + suffix=".go", + syntax_words=go_syntax_words, + syntax_rules=go_syntax_rules, + ) + +**多個副檔名：** + +如果一個語言使用多個副檔名，分別註冊每一個： + +.. code-block:: python + + def register() -> None: + for suffix in (".cpp", ".cxx", ".cc", ".h", ".hpp", ".hxx"): + register_programming_language( + suffix=suffix, + syntax_words=cpp_syntax_words, + syntax_rules=cpp_syntax_rules, + ) + +自然語言（翻譯）插件 +---------------------- + +新增 UI 翻譯語言。 + +**API：** + +.. code-block:: python + + from je_editor.plugins import register_natural_language + + register_natural_language( + language_key="French", # 內部鍵值 + display_name="Francais", # 語言選單顯示名稱 + word_dict={...}, # 翻譯字典 + ) + +``word_dict`` 應包含與 JEditor 內建 ``english_word_dict`` 相同的鍵值。 +常用鍵值包括： + +.. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - 鍵值 + - 說明 + * - ``application_name`` + - 視窗標題 + * - ``file_menu_label`` + - 檔案選單 + * - ``run_menu_label`` + - 執行選單 + * - ``tab_name_editor`` + - 編輯器分頁名稱 + * - ``language_menu_label`` + - 語言選單 + * - ``help_menu_label`` + - 幫助選單 + +完整鍵值列表請參考 ``je_editor.utils.multi_language.english.english_word_dict`` +或範例插件 ``exe/jeditor_plugins/french.py``。 + +**完整範例 — 日語翻譯：** + +.. code-block:: python + + """日語翻譯插件。""" + from je_editor.plugins import register_natural_language + + PLUGIN_NAME = "Japanese Translation" + PLUGIN_AUTHOR = "Your Name" + PLUGIN_VERSION = "1.0.0" + + japanese_word_dict = { + "application_name": "JEditor", + "file_menu_label": "\u30d5\u30a1\u30a4\u30eb", + "run_menu_label": "\u5b9f\u884c", + "tab_name_editor": "\u30a8\u30c7\u30a3\u30bf", + "language_menu_label": "\u8a00\u8a9e", + # ... 更多鍵值 + } + + + def register() -> None: + register_natural_language( + language_key="Japanese", + display_name="\u65e5\u672c\u8a9e", + word_dict=japanese_word_dict, + ) + +執行設定插件 +------------- + +定義如何執行特定類型的檔案。 + +**直譯式語言**（直接執行）： + +.. code-block:: python + + PLUGIN_RUN_CONFIG = { + "name": "Go", # 選單顯示名稱 + "suffixes": (".go",), # 支援的副檔名 + "compiler": "go", # 執行檔 + "args": ("run",), # 檔案路徑前的參數 + } + # 執行：go run file.go + +**編譯式語言**（先編譯再執行）： + +.. code-block:: python + + PLUGIN_RUN_CONFIG = { + "name": "C (GCC)", + "suffixes": (".c",), + "compiler": "gcc", + "args": (), + "compile_then_run": True, # 先編譯再執行 + "output_flag": "-o", # 輸出檔案旗標 + } + # 編譯：gcc file.c -o file + # 執行：./file（Linux/Mac）或 file.exe（Windows） + +**設定鍵值：** + +.. list-table:: + :header-rows: 1 + :widths: 25 15 60 + + * - 鍵值 + - 必要 + - 說明 + * - ``name`` + - 是 + - 執行選單中的顯示名稱 + * - ``suffixes`` + - 是 + - 副檔名元組 + * - ``compiler`` + - 是 + - 編譯器或直譯器的執行檔 + * - ``args`` + - 否 + - 檔案路徑前的額外參數 + * - ``compile_then_run`` + - 否 + - 若為 ``True``，先編譯再執行產出的二進位檔 + * - ``output_flag`` + - 否 + - 輸出檔案旗標（預設 ``"-o"``） + +預建插件 +--------- + +JEditor 在 ``exe/jeditor_plugins/`` 中提供以下範例插件： + +.. list-table:: + :header-rows: 1 + :widths: 30 20 25 25 + + * - 插件 + - 類型 + - 副檔名 + - 執行支援 + * - C 語法高亮 + - 語法 + - ``.c`` + - GCC 編譯與執行 + * - C++ 語法高亮 + - 語法 + - ``.cpp``、``.cxx``、``.cc``、``.h``、``.hpp``、``.hxx`` + - G++ 編譯與執行 + * - Go 語法高亮 + - 語法 + - ``.go`` + - ``go run`` + * - Java 語法高亮 + - 語法 + - ``.java`` + - ``java`` + * - Rust 語法高亮 + - 語法 + - ``.rs`` + - rustc 編譯與執行 + * - 法語翻譯 + - 語言 + - — + - — + +插件瀏覽器 +----------- + +JEditor 包含可從 **Plugin** 選單存取的插件瀏覽器： + +- 瀏覽可用的插件 +- 透過 GitHub API 整合發現社群插件 +- 檢視插件元資料（名稱、作者、版本） diff --git a/docs/source/docs/Zh/zh_index.rst b/docs/source/docs/Zh/zh_index.rst index 7b3d1d4..b25025b 100644 --- a/docs/source/docs/Zh/zh_index.rst +++ b/docs/source/docs/Zh/zh_index.rst @@ -1,8 +1,26 @@ -JEditor 繁體中文 使用文件 ----- +JEditor 繁體中文使用文件 +======================== + +.. image:: image/JEditor.png + :alt: JEditor 截圖 + :align: center + +**JEditor** 是一款以 Python 和 PySide6（Qt for Python）打造的現代化、輕量級且可擴充的程式碼編輯器。 +它是原版 JEditor 的完全重寫版本，效能提升 **10 倍**，同時提供更豐富的功能集。 .. toctree:: - :maxdepth: 4 + :maxdepth: 2 - how_to_use.rst - how_to_extend_using_pyside.rst + getting_started + editor + code_execution + code_quality + git_integration + ai_assistant + console + browser + plugins + configuration + keyboard_shortcuts + api_reference + how_to_extend_using_pyside diff --git a/docs/source/index.rst b/docs/source/index.rst index a7651a6..5f1c866 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,8 +1,18 @@ -Welcome to je_editor's documentation! ----- - -.. toctree:: - :maxdepth: 4 - - docs/Eng/eng_index.rst - docs/Zh/zh_index.rst +Welcome to JEditor's Documentation! +==================================== + +**JEditor** is a modern, lightweight, and extensible code editor built with Python and PySide6. +It provides a rich set of features including multi-tab editing, syntax highlighting, Git integration, +AI assistant, plugin system, and more. + +.. toctree:: + :maxdepth: 2 + :caption: English Documentation + + docs/Eng/eng_index + +.. toctree:: + :maxdepth: 2 + :caption: 繁體中文文件 + + docs/Zh/zh_index diff --git a/je_editor/pyside_ui/code/auto_save/auto_save_manager.py b/je_editor/pyside_ui/code/auto_save/auto_save_manager.py index d5507a6..b881c39 100644 --- a/je_editor/pyside_ui/code/auto_save/auto_save_manager.py +++ b/je_editor/pyside_ui/code/auto_save/auto_save_manager.py @@ -46,7 +46,8 @@ def init_new_auto_save_thread(file_path: str, widget: EditorWidget): # 建立新的自動儲存執行緒，綁定到編輯器 # Create a new auto-save thread for this file widget.code_save_thread = CodeEditSaveThread( - file_to_save=widget.current_file, editor=widget.code_edit + file_to_save=widget.current_file, editor=widget.code_edit, + before_write_callback=widget.mark_ignore_next_file_change, ) # 更新管理字典，記錄該檔案對應的執行緒 diff --git a/je_editor/pyside_ui/code/auto_save/auto_save_thread.py b/je_editor/pyside_ui/code/auto_save/auto_save_thread.py index caef6ff..e7b7259 100644 --- a/je_editor/pyside_ui/code/auto_save/auto_save_thread.py +++ b/je_editor/pyside_ui/code/auto_save/auto_save_thread.py @@ -58,7 +58,8 @@ class CodeEditSaveThread(Thread): """ def __init__( - self, file_to_save: Union[str, None] = None, editor: Union[None, CodeEditor] = None): + self, file_to_save: Union[str, None] = None, editor: Union[None, CodeEditor] = None, + before_write_callback=None): jeditor_logger.info(f"Init CodeEditSaveThread " f"file_to_save: {file_to_save} " f"editor: {editor}") @@ -68,6 +69,7 @@ def __init__( self.still_run: bool = True self.daemon = True self.skip_this_round: bool = False + self.before_write_callback = before_write_callback # 建立主執行緒上的文字提取器 / Create text fetcher on main thread self._text_fetcher: Union[_TextFetcher, None] = None if editor is not None: @@ -102,6 +104,8 @@ def run(self) -> None: try: text = self._get_editor_text() if text is not None: + if self.before_write_callback is not None: + self.before_write_callback() write_file(self.file, text) except Exception as e: jeditor_logger.error(f"Auto-save failed for {self.file}: {e}") diff --git a/je_editor/pyside_ui/main_ui/editor/editor_widget.py b/je_editor/pyside_ui/main_ui/editor/editor_widget.py index 6bb7508..f06fd68 100644 --- a/je_editor/pyside_ui/main_ui/editor/editor_widget.py +++ b/je_editor/pyside_ui/main_ui/editor/editor_widget.py @@ -375,6 +375,13 @@ def dropEvent(self, event: QDropEvent) -> None: self.open_an_file(file_path) event.acceptProposedAction() + def mark_ignore_next_file_change(self) -> None: + """ + 標記下一次檔案變更事件應被忽略（由自動儲存呼叫） + Mark the next file change event to be ignored (called by auto-save before writing) + """ + self._ignore_next_change = True + def _on_file_changed_externally(self, path: str) -> None: """ 檔案被外部修改時提示使用者 @@ -420,6 +427,18 @@ def close(self) -> bool: Close the editor, release resources, and remove auto-save records. """ jeditor_logger.info("EditorWidget close") + + # 先移除檔案監控，防止關閉後仍觸發變更對話框 + # Remove file watcher first to prevent change dialogs after close + watched = self._file_watcher.files() + if watched: + self._file_watcher.removePaths(watched) + + # 停止自動儲存執行緒 / Stop auto-save thread + if self.code_save_thread is not None: + self.code_save_thread.still_run = False + self.code_save_thread = None + # 停止所有正在執行的子程序 / Stop all running subprocesses for mgr in (self.exec_program, self.exec_shell, self.exec_python_debugger): if mgr is not None: @@ -430,9 +449,6 @@ def close(self) -> bool: self.exec_shell = None self.exec_python_debugger = None - if self.code_save_thread is not None: - self.code_save_thread.still_run = False - self.code_save_thread = None if self.current_file: file_is_open_manager_dict.pop(str(Path(self.current_file)), None) auto_save_manager_dict.pop(self.current_file, None) diff --git a/je_editor/pyside_ui/main_ui/main_editor.py b/je_editor/pyside_ui/main_ui/main_editor.py index 97287ff..7533bdb 100644 --- a/je_editor/pyside_ui/main_ui/main_editor.py +++ b/je_editor/pyside_ui/main_ui/main_editor.py @@ -12,7 +12,7 @@ # Import PySide6 core modules from PySide6.QtCore import QTimer, QEvent from PySide6.QtGui import QFontDatabase, QIcon, Qt, QTextCharFormat -from PySide6.QtWidgets import QMainWindow, QWidget, QTabWidget, QLabel, QMessageBox +from PySide6.QtWidgets import QApplication, QMainWindow, QWidget, QTabWidget, QLabel, QMessageBox # 匯入 Qt Material 主題工具 # Import Qt Material style tools from qt_material import QtStyleTools @@ -356,7 +356,9 @@ def startup_setting(self) -> None: # 套用 UI 樣式 (主題) # Apply UI stylesheet (theme) - self.apply_stylesheet(self, user_setting_dict.get("ui_style", "dark_amber.xml")) + app = QApplication.instance() + if app is not None: + self.apply_stylesheet(app, user_setting_dict.get("ui_style", "dark_amber.xml")) # 更新顏色設定 # Update color settings update_actually_color_dict() @@ -459,12 +461,18 @@ def _periodic_save_settings(self) -> None: def closeEvent(self, event) -> None: """ - 視窗關閉事件：儲存使用者設定 - Window close event: save user settings + 視窗關閉事件：關閉所有分頁並儲存使用者設定 + Window close event: close all tabs and save user settings """ jeditor_logger.info("EditorMain closeEvent") if hasattr(self, '_settings_save_timer'): self._settings_save_timer.stop() + # 關閉所有編輯器分頁（停止自動儲存和檔案監控） + # Close all editor tabs (stop auto-save and file watchers) + for i in range(self.tab_widget.count() - 1, -1, -1): + widget = self.tab_widget.widget(i) + if widget and isinstance(widget, EditorWidget): + widget.close() write_user_setting() write_user_color_setting() super().closeEvent(event) @@ -511,7 +519,6 @@ def debug_close(): 除錯模式下自動關閉程式 Auto-close the program in debug mode """ - from PySide6.QtWidgets import QApplication app = QApplication.instance() if app is not None: app.quit() diff --git a/je_editor/pyside_ui/main_ui/menu/style_menu/build_style_menu.py b/je_editor/pyside_ui/main_ui/menu/style_menu/build_style_menu.py index 2995282..6c43568 100644 --- a/je_editor/pyside_ui/main_ui/menu/style_menu/build_style_menu.py +++ b/je_editor/pyside_ui/main_ui/menu/style_menu/build_style_menu.py @@ -5,6 +5,7 @@ # 匯入 Qt 動作 # Import QAction from PySide6.QtGui import QAction +from PySide6.QtWidgets import QApplication # 匯入使用者設定字典，用來保存 UI 樣式設定 # Import user settings dictionary for saving UI style preferences @@ -66,7 +67,9 @@ def set_style(ui_we_want_to_set: EditorMain, action: QAction) -> None: # 呼叫主視窗的 apply_stylesheet 方法，套用選擇的樣式 # Call main window's apply_stylesheet method to apply the chosen style - ui_we_want_to_set.apply_stylesheet(ui_we_want_to_set, action.text()) + app = QApplication.instance() + if app is not None: + ui_we_want_to_set.apply_stylesheet(app, action.text()) # 更新使用者設定，保存目前選擇的樣式 # Update user settings dictionary to persist the chosen style diff --git a/je_editor/start_editor.py b/je_editor/start_editor.py index b4ebab4..c93ec76 100644 --- a/je_editor/start_editor.py +++ b/je_editor/start_editor.py @@ -1,3 +1,4 @@ +import os import sys from PySide6.QtCore import QCoreApplication @@ -44,4 +45,5 @@ def start_editor(debug_mode: bool = False) -> None: # 啟動事件迴圈，並在結束時退出程式 # Start the event loop and exit the program when it ends - sys.exit(new_editor.exec()) + ret = new_editor.exec() + os._exit(ret) diff --git a/je_editor/utils/redirect_manager/redirect_manager_class.py b/je_editor/utils/redirect_manager/redirect_manager_class.py index 89ed86a..cf89f98 100644 --- a/je_editor/utils/redirect_manager/redirect_manager_class.py +++ b/je_editor/utils/redirect_manager/redirect_manager_class.py @@ -14,12 +14,19 @@ class RedirectStdOut(logging.Handler): def __init__(self): super().__init__() + self.encoding = sys.__stdout__.encoding if sys.__stdout__ else "utf-8" def write(self, content_to_write) -> None: # 將輸出內容放入 RedirectManager 的 stdout queue # Put output content into RedirectManager's stdout queue redirect_manager_instance.std_out_queue.put(content_to_write) + def flush(self) -> None: + pass + + def fileno(self) -> int: + return sys.__stdout__.fileno() if sys.__stdout__ else 1 + def emit(self, record: logging.LogRecord) -> None: # 將 logging 訊息格式化後放入 stdout queue # Put formatted logging record into stdout queue @@ -35,12 +42,19 @@ class RedirectStdErr(logging.Handler): def __init__(self): super().__init__() + self.encoding = sys.__stderr__.encoding if sys.__stderr__ else "utf-8" def write(self, content_to_write) -> None: # 將錯誤輸出內容放入 RedirectManager 的 stderr queue # Put error output content into RedirectManager's stderr queue redirect_manager_instance.std_err_queue.put(content_to_write) + def flush(self) -> None: + pass + + def fileno(self) -> int: + return sys.__stderr__.fileno() if sys.__stderr__ else 2 + def emit(self, record: logging.LogRecord) -> None: # 將 logging 訊息格式化後放入 stderr queue # Put formatted logging record into stderr queue diff --git a/pyproject.toml b/pyproject.toml index fc5fe0b..a909ca7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" [project] name = "je_editor" -version = "1.0.8" +version = "1.0.10" authors = [ { name = "JE-Chen", email = "jechenmailman@gmail.com" }, ]