Scripts docs from scripts

blackmamba/script/__init__.py

@@ -1,21 +1,102 @@
 """
-Black Mamba scripts usable as Pythonista action items (wrench icon).
+Following scripts are usable as Pythonista action items (wrench menu icon). In other
+words, you can use them even without external keyboard.
+
+
+Action quickly
+==============
 
 .. automodule:: blackmamba.script.action_quickly
+
+Analyze
+=======
+
 .. automodule:: blackmamba.script.analyze
+
+Clear annotations
+=================
+
 .. automodule:: blackmamba.script.clear_annotations
+
+Close all tabs except current one
+=================================
+
 .. automodule:: blackmamba.script.close_all_tabs_except_current_one
+
+
+Drag & Drop
+===========
+
 .. automodule:: blackmamba.script.drag_and_drop
+
+
+Find usages
+===========
+
 .. automodule:: blackmamba.script.find_usages
+
+
+Jump to definition
+==================
+
 .. automodule:: blackmamba.script.jump_to_definition
+
+
+Jump to line
+============
+
 .. automodule:: blackmamba.script.jump_to_line
+
+
+New file
+========
+
 .. automodule:: blackmamba.script.new_file
+
+
+New tab
+=======
+
 .. automodule:: blackmamba.script.new_tab
+
+
+Open quickly
+============
+
 .. automodule:: blackmamba.script.open_quickly
+
+
+Outline quickly
+===============
+
 .. automodule:: blackmamba.script.outline_quickly
+
+
+Run quickly
+===========
+
 .. automodule:: blackmamba.script.run_quickly
+
+
+Run unit tests
+==============
 .. automodule:: blackmamba.script.run_unit_tests
+
+
+Search Dash
+===========
+
 .. automodule:: blackmamba.script.search_dash
+
+
+Show documentation
+==================
+
 .. automodule:: blackmamba.script.show_documentation
+
+
+Toggle comments
+===============
+
 .. automodule:: blackmamba.script.toggle_comments
 """

blackmamba/script/action_quickly.py

@@ -1,13 +1,11 @@
 #!python3
 """
-Action quickly
-==============
-
-* Script name: ``action_quickly.py``
-* Keyboard shortcut: ``Cmd Shift A``
+Script name ``action_quickly.py``.
 
 Shows dialog with user defined action items (wrench icon). You can filter them
-by title, use arrow keys to change selection and run action with ``Enter`` key.
+by title, use arrow keys to change selection and run any of them with ``Enter`` key.
+
+Only **user defined action items** are listed.
 """
 
 import os

blackmamba/script/analyze.py

@@ -1,10 +1,11 @@
 #!python3
 """
-Analyze
-=======
+Script name ``analyze.py``.
 
-* Script name: ``analyze.py``
-* Keyboard shortcut: ``Ctrl Shift B``
+Source code analysis with ``pep8`` and ``pyflakes``. Results are displayed as
+Pythonista annotations. If there's no error / warning, HUD informs you about that.
+
+This script is configurable, see :ref:`configuration`.
 """
 
 import io

blackmamba/script/clear_annotations.py

@@ -1,10 +1,8 @@
 #!python3
 """
-Clear annotations
-=================
+Script name ``clear_annotations.py``.
 
-* Script name: ``clear_annotations.py``
-* Keyboard shortcut: ``Cmd Shift K``
+Clears all Pythonista annotations.
 """
 
 import editor

blackmamba/script/close_all_tabs_except_current_one.py

@@ -1,10 +1,8 @@
 #!python3
 """
-Close all tabs except current one
-=================================
+Script name ``close_all_tabs_except_current_one.py``.
 
-* Script name: ``close_all_tabs_except_current_one.py``
-* Keyboard shortcut: ``Cmd Shift W``
+Closes all tabs except current one.
 """
 
 import blackmamba.ide.tab as tab

blackmamba/script/drag_and_drop.py

@@ -1,11 +1,18 @@
 #!python3
 """
-Drag & Drop
-===========
+Script name ``drag_and_drop.py``. **iOS >= 11.0 required**.
 
-* Script name: ``drag_and_drop.py``
-* Keyboard shortcut: ``Cmd E``
-* iOS >= 11.0 required
+Shows dialog with opened files and folders tree. You can drag a file / folder to
+any other iOS application. Works well with `Working Copy <http://workingcopyapp.com/>`_
+and `Kaleidoscope <https://www.kaleidoscopeapp.com/>`_ for example.
+
+You can drag a file / folder from any other iOS application as well. But there's one
+limitation, you can drop them at the folder only.
+
+.. note:: If you drop a folder, folder tree is not refreshed. You have to close
+   dialog and open it again to see a new folder. Will be fixed.
+
+This script is configurable, see :ref:`configuration`.
 """
 
 import os

blackmamba/script/find_usages.py

@@ -1,10 +1,11 @@
 #!python3
 """
-Find usages
-===========
+Script name ``find_usages.py``.
 
-* Script name: ``find_usages.py``
-* Keyboard shortcut: ``Ctrl Cmd U``
+Finds usages of a symbol. If there're no usage, HUD informs you.
+Otherwise dialog appears where you can select location and scroll to it.
+
+JEDI must be enabled, see :ref:`configuration`.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

blackmamba/script/jump_to_definition.py

@@ -1,10 +1,12 @@
 #!python3
 """
-Jump to definition
-==================
+Script name ``jump_to_definition.py``.
 
-* Script name: ``jump_to_definition.py``
-* Keyboard shortcut: ``Ctrl Cmd J``
+Jumps to symbol definition. If definition can't be found, HUD informs you.
+Otherwise it jumps to definition location or shows dialog where you can choose
+location if more than one definition was found.
+
+JEDI must be enabled, see :ref:`configuration`.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

blackmamba/script/jump_to_line.py

@@ -1,10 +1,8 @@
 #!python3
 """
-Jump to line
-============
+Script name ``jump_to_line.py``.
 
-* Script name: ``jump_to_line.py``
-* Keyboard shortcut: ``Ctrl L``
+Shows dialog where you can enter line number to scroll to.
 """
 
 import blackmamba.ide.source as source

blackmamba/script/new_file.py

@@ -1,10 +1,8 @@
 #!python3
 """
-New file
-========
+Script name ``new_file.py``.
 
-* Script name: ``new_file.py``
-* Keyboard shortcut: ``Cmd N``
+Shows Pythonista new file dialog.
 """
 
 import blackmamba.ide.tab as tab

blackmamba/script/new_tab.py

@@ -1,10 +1,8 @@
 #!python3
 """
-New tab
-=======
+Script name ``new_tab.py``.
 
-* Script name: ``new_tab.py``
-* Keyboard shortcut: ``Cmd T``
+Creates new empty tab.
 """
 
 import blackmamba.ide.tab as tab

blackmamba/script/open_quickly.py

@@ -1,10 +1,14 @@
 #!python3
 """
-Open quickly
-============
+Script name ``open_quickly.py``.
 
-* Script name: ``open_quickly.py``
-* Keyboard shortcut: ``Cmd Shift O``
+Shows dialog with all your files. You can filter these files by directories,
+file name, etc. Use arrow keys to change selection and then hit ``Enter`` to open
+selected file.
+
+If file is already opened, Black Mamba changes selected tab only.
+
+This script is configurable, see :ref:`configuration`.
 """
 
 import os

blackmamba/script/outline_quickly.py

@@ -1,10 +1,9 @@
 #!python3
 """
-Outline quickly
-===============
+Script name ``outline_quickly.py``.
 
-* Script name: ``outline_quickly.py``
-* Keyboard shortcut: ``Cmd Shift L``
+Shows source code outline. You can filter functions, ... by name. Use arrows key to
+change selection and then hit ``Enter`` to scroll to the symbol.
 """
 
 import editor

blackmamba/script/run_quickly.py

@@ -1,10 +1,12 @@
 #!python3
 """
-Run quickly
-===========
+Script name ``run_quickly.py``.
 
-* Script name: ``run_quickly.py``
-* Keyboard shortcut: ``Cmd Shift R``
+Shows dialog with all your Python files. You can filter these files by directories,
+file name, etc. Use arrows keys to change selection and then hit ``Enter`` to
+run selected file.
+
+This script is configurable, see :ref:`configuration`.
 """
 
 import os

blackmamba/script/run_unit_tests.py

@@ -1,10 +1,10 @@
 #!python3
 """
-Run unit tests
-==============
+Script name ``run_unit_tests.py``.
 
-* Script name: ``run_unit_tests.py``
-* Keyboard shortcut: ``Cmd U``
+Runs unit tests and show results as Pythonista annotations.
+
+This script is configurable, see :ref:`configuration`.
 """
 
 import pytest

blackmamba/script/search_dash.py

@@ -1,10 +1,8 @@
 #!python3
 """
-Search Dash
-===========
+Script name ``search_dash.py``.
 
-* Script name: ``search_dash.py``
-* Keyboard shortcut: ``Cmd Shift 0``
+Opens `Dash <https://kapeli.com/dash_ios>`_ application with selected text or a symbol around cursor position.
 """
 
 import editor

blackmamba/script/show_documentation.py

@@ -1,10 +1,14 @@
 #!python3
 """
-Search documentation
-====================
+Script name ``show_documentation.py``.
 
-* Script name: ``show_documentation.py``
-* Keyboard shortcut: ``Ctrl Cmd ?``
+Shows documentation for the symbol around cursor. If definition can't be found,
+HUD informs you. If there're more than one definitions, dialog appears where
+you can select which one to show.
+
+Documentation is displayed as Pythonista annotation.
+
+JEDI must be enabled, see :ref:`configuration`.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

blackmamba/script/toggle_comments.py

@@ -1,10 +1,8 @@
 #!python3
 """
-Toggle comments
-===============
+Script name ``toggle_comments.py``.
 
-* Script name: ``toggle_comments.py``
-* Keyboard shortcut: ``Cmd /``
+Toggles current line / selected lines comments.
 """
 
 import re