Docs update

zrzka · Oct 10, 2017 · 747a2db · 747a2db
1 parent cfe606e
commit 747a2db
Show file tree

Hide file tree

Showing 13 changed files with 37 additions and 15 deletions.
diff --git a/blackmamba/config.py b/blackmamba/config.py
@@ -7,6 +7,8 @@
 Sections
 ========
 
+.. _configuration-general:
+
 General
 -------
 
@@ -31,6 +33,8 @@
 ``page_line_count: int`` - number of lines to scroll up / down for page up / down.
 
 
+.. _configuration-updates:
+
 Updates
 -------
 
@@ -48,6 +52,7 @@
 ``interval: int`` - check for updates time interval (in seconds).
 
 
+.. _configuration-file_picker:
 
 File picker
 -----------
@@ -76,6 +81,7 @@
 
 Affects Open quickly and Run quickly scripts, see :ref:`scripts`.
 
+.. _configuration-analyzer:
 
 Analyzer
 --------
@@ -115,6 +121,7 @@
 
 Affects Analyze script, see :ref:`scripts`.
 
+.. _configuration-tester:
 
 Tester
 ------
@@ -130,6 +137,7 @@
 
 Affects Run unit tests script, see :ref:`scripts`.
 
+.. _configuration-drag_and_drop:
 
 Drag and Drop
 -------------
@@ -148,6 +156,7 @@
 
 Affects Drag & Drop script, see :ref:`scripts`.
 
+.. _configuration-documentation:
 
 Documentation
 -------------
@@ -161,13 +170,12 @@
         'frame': (630, 110, 730, 350)
     }
 
-Same overlay view is used for consequent show documentation calls if
-``reuse`` is set to ``True``. Otherwise multiple overlays appear in
-consequent show documentation calls, but if symbol's fully qualified name
-matches existing overlay, this particular overlay is expanded (if collapsed)
-and activated.
+``reuse: bool`` - same overlay view is reused for consequent show documentation calls if
+set to ``True``. Otherwise multiple overlays appear in consequent show documentation calls,
+but if a symbol's fully qualified name matches existing overlay, this particular overlay is
+expanded and activated.
 
-``frame`` is in the key window coordinates.
+``frame: tuple(float, float, float, float)`` - initial overlay frame in the key window coordinates.
 
 Affects Show documentation script, see :ref:`scripts`.
 

diff --git a/blackmamba/script/__init__.py b/blackmamba/script/__init__.py
@@ -3,6 +3,11 @@
 words, you can use them even without external keyboard.
 
 
+.. note::
+
+    Scripts still requires you to call :func:`blackmamba.main`, see :ref:`install-startup` section.
+
+
 Action quickly
 ==============
 

diff --git a/blackmamba/script/analyze.py b/blackmamba/script/analyze.py
@@ -5,7 +5,7 @@
 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`.
+This script is configurable, see :ref:`configuration-analyzer` configuration.
 """
 
 import io

diff --git a/blackmamba/script/drag_and_drop.py b/blackmamba/script/drag_and_drop.py
@@ -12,7 +12,7 @@
 .. 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`.
+This script is configurable, see :ref:`configuration-drag_and_drop` configuration.
 """
 
 import os

diff --git a/blackmamba/script/find_usages.py b/blackmamba/script/find_usages.py
@@ -5,7 +5,8 @@
 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`.
+.. note::
+    JEDI must be enabled, see :ref:`configuration-general` configuration.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

diff --git a/blackmamba/script/jump_to_definition.py b/blackmamba/script/jump_to_definition.py
@@ -6,7 +6,8 @@
 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`.
+.. note::
+    JEDI must be enabled, see :ref:`configuration-general` configuration.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

diff --git a/blackmamba/script/open_quickly.py b/blackmamba/script/open_quickly.py
@@ -8,7 +8,7 @@
 
 If file is already opened, Black Mamba changes selected tab only.
 
-This script is configurable, see :ref:`configuration`.
+This script is configurable, see :ref:`configuration-file_picker` configuration.
 """
 
 import os

diff --git a/blackmamba/script/run_quickly.py b/blackmamba/script/run_quickly.py
@@ -6,7 +6,7 @@
 file name, etc. Use arrows keys to change selection and then hit ``Enter`` to
 run selected file.
 
-This script is configurable, see :ref:`configuration`.
+This script is configurable, see :ref:`configuration-file_picker` configuration.
 """
 
 import os

diff --git a/blackmamba/script/run_unit_tests.py b/blackmamba/script/run_unit_tests.py
@@ -4,7 +4,7 @@
 
 Runs unit tests and show results as Pythonista annotations.
 
-This script is configurable, see :ref:`configuration`.
+This script is configurable, see :ref:`configuration-tester` configuration.
 """
 
 import pytest

diff --git a/blackmamba/script/show_documentation.py b/blackmamba/script/show_documentation.py
@@ -7,9 +7,12 @@
 you can select which one to show.
 
 Documentation is displayed as an overlay, which can be closed by the
-``Ctrl-W`` shortcut or by tapping on the ``X`` button.
+``Ctrl W`` shortcut or by tapping on the ``X`` button.
 
-JEDI must be enabled, see :ref:`configuration`.
+This script is configurable, see :ref:`configuration-documentation` configuration.
+
+.. note::
+    JEDI must be enabled, see :ref:`configuration-general` configuration.
 """
 
 from blackmamba.uikit.picker import PickerView, PickerItem, PickerDataSource

diff --git a/docs/source/_static/images/docstrings.jpeg b/docs/source/_static/images/docstrings.jpeg
diff --git a/docs/source/user/install.rst b/docs/source/user/install.rst
@@ -35,6 +35,7 @@ PIP
 Black Mamba no longer supports installation via ``pip``. Latest available
 release is 1.0.2.
 
+.. _install-startup:
 
 Startup
 -------

diff --git a/docs/source/user/shortcuts.rst b/docs/source/user/shortcuts.rst
@@ -67,8 +67,11 @@ Shortcut          Function
 ``Ctrl Cmd J``    Jump to definition
 ``Ctrl Cmd U``    Find usages
 ``Ctrl Cmd ?``    Show documentation
+``Ctrl W``        Close active overlay [#f1]_
 ================  ========
 
+.. [#f1] Show documentation script does use overlays.
+
 Just hold ``Cmd`` key and iOS will show you all available shortcuts
 if you can't remember them.