From 7cd90ac6742dec94501ad4044e568bf4bcb2fd06 Mon Sep 17 00:00:00 2001 From: guillermooo Date: Sat, 20 Dec 2014 23:23:42 +0100 Subject: [PATCH 1/3] wip: plugins topic --- source/reference/plugins/basics.rst | 212 ++++++++++++++++++ .../plugins/tutorial_simple_plugin.rst | 47 ++++ 2 files changed, 259 insertions(+) create mode 100644 source/reference/plugins/basics.rst create mode 100644 source/reference/plugins/tutorial_simple_plugin.rst diff --git a/source/reference/plugins/basics.rst b/source/reference/plugins/basics.rst new file mode 100644 index 0000000..438464d --- /dev/null +++ b/source/reference/plugins/basics.rst @@ -0,0 +1,212 @@ +================= +Plugins -- Basics +================= + +.. seealso:: + + :doc:`API Reference <../../reference/api>` + More information on the Python API. + + :doc:`Plugins Reference <../../reference/plugins>` + More information about plugins. + + +Overview +======== + +This section is intended for users with programming skills. + +Sublime Text can be extended +through Python plugins. +Plugins build features +by reusing existing commands +or creating new ones + +.. note:: + + Plugins range from the very simple + (a single file and a single command) + to complex, multi-file plugins. + + The most complex plugins + are often included in + a lager package. + + +Prerequisites +============= + +In order to write plugins, you must be able to program in Python_. +At the time of this writing, Sublime Text used Python 3.3.3. + +.. _Python: http://www.python.org + + +Where to Store Plugins +********************** + +Sublime Text will look for plugins in these places: + +* ``Installed Packages`` directory (only *.sublime-package* files) +* ``Packages`` directory +* ``Packages//`` directories + +Keeping plugins directly under ``Packages`` is discouraged. + + +Anatomy of a Plugin +=================== + +This is a sample plugin:: + + import sublime + import sublime_plugin + + class MyFirstPluginCommand(sublime_plugin.TextCommand): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + def run(self, edit): + self.view.insert(edit, 0, 'hello world!') + + +The ``sublime`` and the ``sublime_plugin`` modules +are provided by Sublime Text; +they are not part +of the Python standard library. + +As mentioned earlier, +plugins reuse or create *commands*. +Commands are +an essential building block in Sublime Text. +Commands are simply Python classes +that can be called +from different places, +like the plugin API, menu files, macros, etc. + +Sublime Text commands derive from the ``*Command`` classes defined in +``sublime_plugin`` (more on this later). + +The rest of the code in our example is concerned with particulars of +``TextCommand`` or the API. We'll discuss those topics in later sections. + + +Conventions for Command Names +***************************** + +Our command is named ``MyFirstPluginCommand``. +Using the ``*Command`` suffix +for command classes is customary. + + +Sublime Text transforms command names +by stripping the ``Command`` suffix +and separating ``PhrasesLikeThis`` +with underscores, like so: +``phrases_like_this``. + +Therefore, our sample plugin +must be called as follows +whenever needed:: + + my_first_plugin + +New commands should follow the same naming pattern. + + +Types of Commands +================= + +You can create the following types of commands: + +* Window commands (``sublime_plugin.WindowCommand``) +* Text commands (``sublime_plugin.TextCommand``) +* Application commands (``sublime_plugin.ApplicationCommand``) + +When writing plugins, +consider your goal +and choose the appropriate type of command. + + +Shared Traits of Commands +************************* + +All commands +need to implement a ``.run()`` method +in order to work. +The ``.run()`` method +can receive an arbitrarily long number +of keyword parameters. + +.. note:: + Arguments to commands + must be JSON types + due to how Sublime Text + serializes them internally. + + +Window Commands +*************** + +Window commands operate at the window level. This doesn't mean that you can't +manipulate views from window commands, but rather that you don't need views in +order for window commands to be available. For instance, the built-in command +``new_file`` is defined as a ``WindowCommand`` so it works even when no view +is open. Requiring a view to exist in that case wouldn't make sense. + +Window command instances have a ``.window`` attribute to point to the window +instance that created them. + +The ``.run()`` method of a window command doesn't require any positional +parameter. + +Window commands are able to route text commands to their window's active view. + +Text Commands +------------- + +Text commands operate at the view level, so they require a view to exist +in order to be available. + +Text command instances have a ``.view`` attribute pointing to the view instance +that created them. + +The ``.run()`` method of text commands requires an ``edit`` instance as +its first positional argument. + +Text Commands and the ``edit`` Object +------------------------------------- + +The edit object groups modifications to the view so that undo and macros work +sensibly. + +**Note:** Contrary to older versions, Sublime Text 3 doesn't allow programmatic +control over edit objects. The API is in charge of managing their life cycle. +Plugin creators must ensure that all modifying operations occur inside the +``.run`` method of new text commands. To call existing commands, you can use +``view.run_command(, )`` or similar API calls. + +Responding to Events +-------------------- + +Any command deriving from ``EventListener`` will be able to respond to events. + + +.. _plugins-completions-example: + +commands +naming +calling from where +what is a plugin +where +why +api (sync/async) +python version + + +events +async +completions +on query contexts +groups +layouts diff --git a/source/reference/plugins/tutorial_simple_plugin.rst b/source/reference/plugins/tutorial_simple_plugin.rst new file mode 100644 index 0000000..a68ff06 --- /dev/null +++ b/source/reference/plugins/tutorial_simple_plugin.rst @@ -0,0 +1,47 @@ +======================= +Writing a Simple Plugin +======================= + + +Overview +======== + +In this tutorial +we'll write a simple plugin +that inserts the string +``Hello World!`` into the active buffer. + + + +Writing the Plugin +================== + +1. Create a new buffer (:kbd:`Ctrl+N`) +2. Type in the following: + +:: + + import sublime + import sublime_plugin + + class InsertHelloWorldCommand(sublime_plugin.TextCommand): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + def run(self, edit): + self.view.insert(edit, 0, 'Hello world!') + + +3. Save to ``Packages/User/hello_world.py``. + +Now our plugin has been saved +to a location where Sublime Text +can find it. +Let's use it. + +#. Create a new buffer (:kbd:`Ctrl+N`) +#. Open the Python console (:kbd:`Ctrl+``) +#. Type: ``view.run_command("insert_hello_world")`` and press :kbd:`Return`. + +You should see the text "Hello, World!" in the newly created buffer. + From 68fd240c196c32018a87c446029cd5415a8cc2dd Mon Sep 17 00:00:00 2001 From: guillermooo Date: Sun, 21 Dec 2014 09:33:25 +0100 Subject: [PATCH 2/3] edit --- source/reference/plugins.rst | 140 +---------------- source/reference/plugins/basics.rst | 223 +++++++++++++++++++++------- 2 files changed, 172 insertions(+), 191 deletions(-) diff --git a/source/reference/plugins.rst b/source/reference/plugins.rst index f04a18b..4d9d960 100644 --- a/source/reference/plugins.rst +++ b/source/reference/plugins.rst @@ -1,139 +1,11 @@ Plugins ======= -.. seealso:: +Sublime Text can be extended +with plugins written in Python. - :doc:`API Reference <../reference/api>` - More information on the Python API. +.. toctree:: + :maxdepth: 3 - -Plugins are Python scripts implementing ``*Command`` classes from -``sublime_plugin``. - - -Where to Store Plugins -********************** - -Sublime Text will look for plugins in these places: - -* ``Packages`` -* ``Packages/`` -* ``.sublime-package`` files - -Plugin files nested deeper in ``Packages`` won't be loaded. - -All plugins should live inside a folder of their own and not directly -under ``Packages``. This will spare you confusions when Sublime Text attempts -to sort packages for loading. - - -Conventions for Command Names -***************************** - -By convention, Sublime Text command class names are suffixed with ``Command`` -and written as ``NamesLikeThisCommand``. - -However, command names are automatically transformed from ``NamesLikeThisCommand`` -to ``name_like_this``. Thus, ``ExampleCommand`` would become ``example``, -and ``AnotherExampleCommand`` would become ``another_example``. - -In names for classes defining commands, use ``NameLikeThisCommand``. To call a -command from the API, use the standardized ``name_like_this``. - - -Types of Commands -***************** - -* ``sublime_plugin.WindowCommand`` -* ``sublime_plugin.TextCommand`` -* ``sublime_plugin.EventListener`` - -Instances of ``WindowCommand`` have a ``.window`` attribute pointing to the -window instance that created them. Similarly, instances of ``TextCommand`` -have a ``.view`` attribute. - -Shared Traits for Commands --------------------------- - -All commands must implement a ``.run()`` method. - -All commands can receive an arbitrarily long number of keyword arguments that -must be valid JSON types. - - -How to Call Commands from the API -********************************* - -Depending on the type of command, use a reference to a ``View`` or a ``Window`` -and call ``.run_command('command_name')``. In addition to the command's -name, ``.run_command`` accepts a dictionary whose keys are the names of valid -parameters for said command:: - - window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."}) - - -Command Arguments -***************** - -All user-provided arguments to commands must be valid JSON types. - - -Text Commands and the ``edit`` Object -************************************* - -Text commands receive and ``edit`` object passed to them by Sublime Text. - -All actions done within an ``edit`` are grouped as a single undo action. -Callbacks such as ``on_modified()`` and ``on_selection_modified()`` are called -when the edit is finished. - -.. XXX: Is the above true? - -Contrary to earlier versions of Sublime Text, the ``edit`` object's life time is -now managed solely by the editor. Plugin authors must ensure to perform all -editing operations within the ``run()`` method of text commands so that macros -and repeating commands work as expected. - -To call other commands from your own commands, use the ``run_command()`` -function. - - -Responding to Events -******************** - -Any subclass of ``EventListener`` will be able to respond to events. You cannot -make a class derive both from ``EventListener`` and from any other type of -command. - -.. sidebar:: A Word of Warning about ``EventListener`` - - Expensive operations in event listeners can cause Sublime Text to become - unresponsive, especially in events triggered frequently, like - ``on_modified()`` and ``on_selection_modified()``. Be careful of how much - work is done in these and don't implement events you don't need, even if - they just ``pass``. - - -Sublime Text and the Python Standard Library -******************************************** - -Sublime Text ships with a trimmed down standard library. - - -Automatic Plugin Reload -*********************** - -Sublime Text will reload top-level Python modules as they change (perhaps -because you are editing a *.py* file within *Packages*). By contrast, Python -subpackages won't be reloaded automatically, and this can lead to confusion -while you're developing plugins. Generally speaking, it's best to restart -Sublime Text after you've made changes to plugin files, so all changes can take -effect. - - -Multithreading -************** - -Only the ``set_timeout()`` function is safe to call from different threads. - -.. XXX: Is this still true? + Basics + Tutorial -- Writing a Simple Plugin diff --git a/source/reference/plugins/basics.rst b/source/reference/plugins/basics.rst index 438464d..4370164 100644 --- a/source/reference/plugins/basics.rst +++ b/source/reference/plugins/basics.rst @@ -2,56 +2,87 @@ Plugins -- Basics ================= -.. seealso:: - :doc:`API Reference <../../reference/api>` - More information on the Python API. +Prerequisites +============= - :doc:`Plugins Reference <../../reference/plugins>` - More information about plugins. +This section is intended +for users with programming skills. + +In order to write plugins, +you must be able to program in Python_. +At the time of this writing, +Sublime Text used Python 3.3.3. + +.. _Python: http://www.python.org Overview ======== -This section is intended for users with programming skills. - Sublime Text can be extended through Python plugins. Plugins build features by reusing existing commands -or creating new ones +or creating new ones. .. note:: Plugins range from the very simple (a single file and a single command) to complex, multi-file plugins. - - The most complex plugins + The more complex plugins are often included in - a lager package. + a larger package. -Prerequisites -============= +What's a Command? +================= -In order to write plugins, you must be able to program in Python_. -At the time of this writing, Sublime Text used Python 3.3.3. +A command is a basic unit of functionality +in Sublime Text. +Most editor actions are encapsulated +as commands: +moving the caret; editing operations +like deleting, inserting characters, etc; +but also creating buffers, +new windows; showing panels... -.. _Python: http://www.python.org +As mentioned earlier, +plugins reuse or create commands. +In concrete terms, +commands are simply Python classes +that can be called +from different places, +like the plugin API, menu files, macros, +key maps, etc. +Some commands take optional +or mandatory arguments. -Where to Store Plugins -********************** +Here's an example of a command call +from a window object:: -Sublime Text will look for plugins in these places: + window.run_command("echo", {"Hello": "World"}) + +We'll see examples +of creating commands +in later sections. + + +Where to Store Plugin Files +=========================== + +Sublime Text will look for Python files +containing plugins +in these places: -* ``Installed Packages`` directory (only *.sublime-package* files) * ``Packages`` directory * ``Packages//`` directories +* ``Installed Packages`` directory (only *.sublime-package* files) -Keeping plugins directly under ``Packages`` is discouraged. +Keeping plugins directly under ``Packages`` +is discouraged. Anatomy of a Plugin @@ -62,7 +93,8 @@ This is a sample plugin:: import sublime import sublime_plugin - class MyFirstPluginCommand(sublime_plugin.TextCommand): + + class InsertHelloWorldCommand(sublime_plugin.TextCommand): def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) @@ -91,11 +123,11 @@ The rest of the code in our example is concerned with particulars of ``TextCommand`` or the API. We'll discuss those topics in later sections. -Conventions for Command Names -***************************** +Naming Conventions for ``*Command`` Subclasses +********************************************** -Our command is named ``MyFirstPluginCommand``. -Using the ``*Command`` suffix +Our previous command is named ``InsertHelloWorldCommand``. +Using the ``Command`` suffix for command classes is customary. @@ -109,7 +141,7 @@ Therefore, our sample plugin must be called as follows whenever needed:: - my_first_plugin + insert_hello_world New commands should follow the same naming pattern. @@ -123,13 +155,20 @@ You can create the following types of commands: * Text commands (``sublime_plugin.TextCommand``) * Application commands (``sublime_plugin.ApplicationCommand``) +Additionally, you can create +classes that respond to editor events +by deriving from ``sublime_plugin.EventListener``. + +We'll discuss each type of command +in later sections. + When writing plugins, consider your goal -and choose the appropriate type of command. +and choose the most appropriate type of command. -Shared Traits of Commands -************************* +The ``.run()`` Method in Commands +********************************* All commands need to implement a ``.run()`` method @@ -138,6 +177,9 @@ The ``.run()`` method can receive an arbitrarily long number of keyword parameters. +.. XXX: about params, can ApplicationCommand's receive +.. params? + .. note:: Arguments to commands must be JSON types @@ -148,11 +190,19 @@ of keyword parameters. Window Commands *************** -Window commands operate at the window level. This doesn't mean that you can't -manipulate views from window commands, but rather that you don't need views in -order for window commands to be available. For instance, the built-in command -``new_file`` is defined as a ``WindowCommand`` so it works even when no view -is open. Requiring a view to exist in that case wouldn't make sense. +Window commands operate +at the window level. +Therefore, you don't need views +in order for window commands +to be available. +For instance, +the built-in command ``new_file`` +is defined as a ``WindowCommand`` +so it works +even when no view is open. +Requiring a view to exist +in that case +wouldn't make sense. Window command instances have a ``.window`` attribute to point to the window instance that created them. @@ -160,10 +210,16 @@ instance that created them. The ``.run()`` method of a window command doesn't require any positional parameter. -Window commands are able to route text commands to their window's active view. +Despite not requiring an active view, +window commands are able +to route text commands +to their window's active view, +so it's possible to call +a ``TextCommand`` from a ``WindowCommand``. + Text Commands -------------- +************* Text commands operate at the view level, so they require a view to exist in order to be available. @@ -174,39 +230,92 @@ that created them. The ``.run()`` method of text commands requires an ``edit`` instance as its first positional argument. + Text Commands and the ``edit`` Object ------------------------------------- The edit object groups modifications to the view so that undo and macros work sensibly. -**Note:** Contrary to older versions, Sublime Text 3 doesn't allow programmatic -control over edit objects. The API is in charge of managing their life cycle. Plugin creators must ensure that all modifying operations occur inside the -``.run`` method of new text commands. To call existing commands, you can use +``.run()`` method of new text commands. To call existing commands, you can use ``view.run_command(, )`` or similar API calls. + Responding to Events --------------------- +==================== + +Any subclass of ``EventListener`` will be able to respond to events. You cannot +make a class derive both from ``EventListener`` and from any other type of +command. + +.. warning:: + + Expensive operations in event listeners can cause Sublime Text to become + unresponsive, especially in events triggered frequently, like + ``.on_modified()`` and ``.on_selection_modified()``. Be careful of how much + work is done in these and don't implement events you don't need, even if + they just ``pass``. + + +How to Call Commands from the API +================================= + +Depending on the type of command, +use a reference to a ``View`` or a ``Window`` +and call ``.run_command('command_name')``. +In addition to the command's name, +``.run_command()`` accepts a dictionary +whose keys are the names +of valid parameters for said command:: + + window.run_command("echo", {"Tempus": "Irreparabile", "Fugit": "."}) -Any command deriving from ``EventListener`` will be able to respond to events. +.. XXX: check the following +Application commands can be called +either from the command line +or using ``sublime.run_command()``. -.. _plugins-completions-example: +Sublime Text and the Python Standard Library +============================================ -commands -naming -calling from where -what is a plugin -where -why -api (sync/async) -python version +Sublime Text ships with a trimmed down standard library. +Not all modules are available from a plugin. -events -async -completions -on query contexts -groups -layouts +Automatic Plugin Reload +======================= + +Sublime Text will reload top-level Python modules as they change (perhaps +because you are editing a *.py* file within *Packages*). By contrast, Python +subpackages won't be reloaded automatically, and this can lead to confusion +while you're developing plugins. Generally speaking, it's best to restart +Sublime Text after you've made changes to plugin files, so all changes can take +effect. + + +.. commands +.. naming +.. calling from where +.. what is a plugin +.. where +.. why +.. api (sync/async) +.. python version + + +.. events +.. async +.. completions +.. on query contexts +.. groups +.. layouts + +.. seealso:: + + :doc:`API Reference <../../reference/api>` + More information on the Python API. + + :doc:`Plugins Reference <../../reference/plugins>` + More information about plugins. From c065e7d95a72a6d62d8807a53fff8cfc5848e358 Mon Sep 17 00:00:00 2001 From: guillermooo Date: Thu, 25 Dec 2014 18:12:59 +0100 Subject: [PATCH 3/3] move files; edit --- source/extensibility/plugins.rst | 229 +----------------- source/extensibility/plugins/api.rst | 10 + .../plugins/basics.rst | 0 .../plugins/tutorial_simple_plugin.rst | 0 source/reference/plugins.rst | 11 - source/reference/reference.rst | 1 - 6 files changed, 17 insertions(+), 234 deletions(-) create mode 100644 source/extensibility/plugins/api.rst rename source/{reference => extensibility}/plugins/basics.rst (100%) rename source/{reference => extensibility}/plugins/tutorial_simple_plugin.rst (100%) delete mode 100644 source/reference/plugins.rst diff --git a/source/extensibility/plugins.rst b/source/extensibility/plugins.rst index 5061ffd..2772993 100644 --- a/source/extensibility/plugins.rst +++ b/source/extensibility/plugins.rst @@ -1,227 +1,12 @@ -======= Plugins ======= -.. seealso:: - - :doc:`API Reference <../reference/api>` - More information on the Python API. - - :doc:`Plugins Reference <../reference/plugins>` - More information about plugins. - -This section is intended for users with programming skills. - - -Sublime Text can be extended through Python plugins. Plugins build features by -reusing existing commands or creating new ones. Plugins are a logical entity, -rather than a physical one. - - -Prerequisites -************* - -In order to write plugins, you must be able to program in Python_. -At the time of this writing, Sublime Text used Python 3. - -.. _Python: http://www.python.org - - -Where to Store Plugins -********************** - -Sublime Text will look for plugins only in these places: - -* ``Installed Packages`` (only *.sublime-package* files) -* ``Packages`` -* ``Packages//`` - -As a consequence, any plugin nested deeper in ``Packages`` won't be loaded. - -Keeping plugins directly under ``Packages`` is discouraged. Sublime Text sorts -packages in a predefined way before loading them, so if you save plugin files -directly under ``Packages`` you might get confusing results. - - -Your First Plugin -***************** - -Let's write a "Hello, World!" plugin for Sublime Text: - -#. Select **Tools | New Plugin...** in the menu. -#. Save to ``Packages/User/hello_world.py``. - -You've just written your first plugin! Let's put it to use: - -#. Create a new buffer (``Ctrl+n``). -#. Open the Python console (``Ctrl+```). -#. Type: ``view.run_command("example")`` and press enter. - -You should see the text "Hello, World!" in the newly created buffer. - - -Analyzing Your First Plugin -*************************** - -The plugin created in the previous section should look roughly like this:: - - import sublime, sublime_plugin - - class ExampleCommand(sublime_plugin.TextCommand): - def run(self, edit): - self.view.insert(edit, 0, "Hello, World!") - - -Both the ``sublime`` and ``sublime_plugin`` modules are provided by -Sublime Text; they are not part of the Python standard library. - -As we mentioned earlier, plugins reuse or create *commands*. Commands are an -essential building block in Sublime Text. They are simply Python classes -that can be called in similar ways from different Sublime Text facilities, -like the plugin API, menu files, macros, etc. - -Sublime Text Commands derive from the ``*Command`` classes defined in -``sublime_plugin`` (more on this later). - -The rest of the code in our example is concerned with particulars of -``TextCommand`` or with the API. We'll discuss those topics in later sections. - -Before moving on, though, we'll look at how we invoked the new command: first -we opened the Python console and then we issued a call to -``view.run_command()``. This is a rather inconvenient way of calling commands, -but it's often useful when you're in the development phase of a plugin. For -now, keep in mind that your commands can be accessed through key bindings -and by other means, just like other commands. - -Conventions for Command Names ------------------------------ - -You may have noticed that our command is named ``ExampleCommand``, but we -passed the string ``example`` to the API call instead. This is necessary -because Sublime Text standardizes command names by stripping the ``Command`` -suffix and separating ``PhrasesLikeThis`` with underscores, like so: -``phrases_like_this``. - -New commands should follow the same naming pattern. - - -Types of Commands -***************** - -You can create the following types of commands: - -* Window commands (``sublime_plugin.WindowCommand``) -* Text commands (``sublime_plugin.TextCommand``) - -When writing plugins, consider your goal and choose the appropriate type of -commands. - - -Shared Traits of Commands -------------------------- - -All commands need to implement a ``.run()`` method in order to work. Additionally, -they can receive an arbitrarily long number of keyword parameters. - -**Note:** Parameters to commands must be valid JSON values due to how ST -serializes them internally. - -Window Commands ---------------- - -Window commands operate at the window level. This doesn't mean that you can't -manipulate views from window commands, but rather that you don't need views in -order for window commands to be available. For instance, the built-in command -``new_file`` is defined as a ``WindowCommand`` so it works even when no view -is open. Requiring a view to exist in that case wouldn't make sense. - -Window command instances have a ``.window`` attribute to point to the window -instance that created them. - -The ``.run()`` method of a window command doesn't require any positional -parameter. - -Window commands are able to route text commands to their window's active view. - -Text Commands -------------- - -Text commands operate at the view level, so they require a view to exist -in order to be available. - -Text command instances have a ``.view`` attribute pointing to the view instance -that created them. - -The ``.run()`` method of text commands requires an ``edit`` instance as -its first positional argument. - -Text Commands and the ``edit`` Object -------------------------------------- - -The edit object groups modifications to the view so that undo and macros work -sensibly. - -**Note:** Contrary to older versions, Sublime Text 3 doesn't allow programmatic -control over edit objects. The API is in charge of managing their life cycle. -Plugin creators must ensure that all modifying operations occur inside the -``.run`` method of new text commands. To call existing commands, you can use -``view.run_command(, )`` or similar API calls. - -Responding to Events --------------------- - -Any command deriving from ``EventListener`` will be able to respond to events. - - -.. _plugins-completions-example: - -Another Plugin Example: Feeding the Completions List ----------------------------------------------------- - -Let's create a plugin that fetches data from Google's Autocomplete service and -then feeds it to the Sublime Text completions list. Please note that, as ideas -for plugins go, this a very bad one. - -.. sourcecode:: py - - import sublime, sublime_plugin - - from xml.etree import ElementTree as ET - from urllib import urlopen - - GOOGLE_AC = r"http://google.com/complete/search?output=toolbar&q=%s" - - class GoogleAutocomplete(sublime_plugin.EventListener): - def on_query_completions(self, view, prefix, locations): - elements = ET.parse( - urlopen(GOOGLE_AC % prefix) - ).getroot().findall("./CompleteSuggestion/suggestion") - - sugs = [(x.attrib["data"],) * 2 for x in elements] - - return sugs - -.. note:: - Make sure you don't keep this plugin around after trying it or it will - interfere with the autocompletion system. - -.. seealso:: - - .. py:currentmodule:: sublime_plugin - - :py:meth:`EventListener.on_query_completions` - Documentation on the API event used in this example. - - -Learning the API -**************** +Sublime Text can be extended +with plugins written in Python. -In order to create plugins, you need to get acquainted with the Sublime Text -API and the available commands. Documentation on both is scarce at the time of -this writing, but you can read existing code and learn from it. +.. toctree:: + :maxdepth: 3 -In particular, the :file:`Packages/Default` contains many examples of -undocumented commands and API calls. Note that you will first have to extract -its content to a folder if you want to take a look at the code within. As an -exercise, you can try creating a build system to do that on demand, and a -project file to be able to peek at the sample code easily. + Basics + Plugin API + Tutorial -- Writing a Simple Plugin diff --git a/source/extensibility/plugins/api.rst b/source/extensibility/plugins/api.rst new file mode 100644 index 0000000..2cc1c54 --- /dev/null +++ b/source/extensibility/plugins/api.rst @@ -0,0 +1,10 @@ +========== +Python API +========== + + +Overview +======== + +Sublime Text exposes its functionality +trough a Python API. \ No newline at end of file diff --git a/source/reference/plugins/basics.rst b/source/extensibility/plugins/basics.rst similarity index 100% rename from source/reference/plugins/basics.rst rename to source/extensibility/plugins/basics.rst diff --git a/source/reference/plugins/tutorial_simple_plugin.rst b/source/extensibility/plugins/tutorial_simple_plugin.rst similarity index 100% rename from source/reference/plugins/tutorial_simple_plugin.rst rename to source/extensibility/plugins/tutorial_simple_plugin.rst diff --git a/source/reference/plugins.rst b/source/reference/plugins.rst deleted file mode 100644 index 4d9d960..0000000 --- a/source/reference/plugins.rst +++ /dev/null @@ -1,11 +0,0 @@ -Plugins -======= - -Sublime Text can be extended -with plugins written in Python. - -.. toctree:: - :maxdepth: 3 - - Basics - Tutorial -- Writing a Simple Plugin diff --git a/source/reference/reference.rst b/source/reference/reference.rst index 9c09b25..96ad71f 100644 --- a/source/reference/reference.rst +++ b/source/reference/reference.rst @@ -19,7 +19,6 @@ general index. comments metadata Command Palette - plugins api commands keyboard_shortcuts_win