[docs] add rough draft of API style guide

docs/api/guides.rst

@@ -0,0 +1,100 @@
+Guides
+=======
+
+A VisiData Guide is a more verbose writeup of a particular set of features that explains how the features work together.  Guides are readable from within VisiData itself.
+
+The Guide Index is accessible with ``Space open-guide-index`` within VisiData or ``vd -P open-guide-index`` from the CLI.
+
+
+.. note::
+
+    Guides that have not been written yet are grayed out.  We love to get help with documentation, please get in touch if you want to write one or have other suggestions!
+
+Here's an outline for adding a guide, with our writing style preferences:
+
+1. Launch **GuideGuide** and find the ``name`` of the guide
+2. ``GuideSheet`` subclass
+3. Add docstring to its ``guide`` variable
+4. ``vd.addGuide`` boilerplate to let VisiData know about the guide
+
+Hello Guide
+------------
+
+This same general structure and process should work for most guides.
+
+Step 1. Launch **GuideGuide** and find the ``name`` of the guide
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. image:: ../assets/guide.png
+    :width: 1000
+
+Within VisiData, ``Space open-guide-index`` to see the Table of Contents.
+
+``gv`` will show the **name** column. Choose a guide to work on, and note down its **name**. For example: **MacrosSheet**.
+
+::
+
+Step 2. Create a GuideSheet subclass
+------------------------------------
+
+::
+
+    class MacrosGuide(GuideSheet):
+        guide = ''
+
+-  The Guide should be the final class declaration in the Python file
+   where the bulk of the code for that feature exists. In this case,
+   we would add it to ``visidata/macros.py``.
+
+-  All Guides inherit from ``GuideSheet``.
+
+- The class name does not have to match the guide's **name**.
+
+.. autoclass:: visidata.GuideSheet
+
+Step 3. Add docstring to the ``guide`` variable
+----------------------------------------------
+
+Next fill out the text for the guide in the ``guide`` variable:
+
+::
+
+    class MacrosGuide(GuideSheet):
+        guide='''# Macros
+    Macros allow you to bind a command sequence to a keystroke or longname, to replay when that keystroke is pressed or the command is executed by longname.
+
+    The basic usage is:
+        1. `m` (`macro-record`) to begin recording the macro.
+        2. Execute a series of commands.
+        3. `m` again to complete the recording, and prompt for the keystroke or longname to bind it to.
+
+    # The Macros Sheet
+
+    - `gm` (`macro-sheet`) to open an index of existing macros.
+
+    - `d` (`delete-row`) to mark macros for deletion.
+    - `z Ctrl+S` (`commit-sheet`) to then commit any changes.
+    '''
+
+Some stylings of note:
+
+- `Basic markdown <https://www.markdownguide.org/basic-syntax/>`_ will work. VisiData supports # Headings, \*\*bold\*\*, \*italics\*, \`code snippets\`, and \_underscore\_.
+- VisiData has its `own display attribute syntax </docs/colors#attrs>`_. For e.g., ``[:onclick url]text[/]`` will format ``text`` into a clickable url that will open in ``$BROWSER``. ``[:red on black]sentence[/]`` will change the colour of ``sentence`` to be red text on black background.
+- For listing relevant commands, the general pattern should be ``- `keystroke` (`longname`) to {helpstring}``.  The keystroke should immediately follow the bullet; do not say "Press" or "Use" within VisiData docs and helpstrings.
+- Generally, the second person perspective ("you", "yours") is not used outside of tutorials.
+
+Step 4. Let VisiData know about the guide
+-----------------------------------------
+
+At the bottom of the file, add ``vd.addGuide('GuideName', GuideClass)``.
+
+Finishing off our example:
+
+::
+
+        vd.addGuide('MacrosSheet', MacrosGuide)
+
+``vd.getGuide`` will now be able to locate the guide!
+
+.. autofunction:: visidata.vd.addGuide
+.. autofunction:: visidata.vd.getGuide

docs/api/index.rst

@@ -44,6 +44,7 @@ This extends VisiData so that when :kbd:`1` is pressed on any sheet, the command
    modify
    interface
    async
+   guides
    plugins
 
 ----

visidata/guide.py

@@ -1,6 +1,6 @@
 '''
 # A Guide to VisiData Guides
-Each guide shows you how to use a particular feature in VisiData. Gray guides have not been written yet. We love contributions: [:onclick https://visidata.org/docs/guides]https://visidata.org/docs/guides[/].
+Each guide shows you how to use a particular feature in VisiData. Gray guides have not been written yet. We love contributions: [:onclick https://visidata.org/docs/guides]https://visidata.org/docs/api/guides[/].
 
 - [:keystrokes]Up/Down[/] to move the row cursor
 - [:keystrokes]Enter[/] to view a topic

visidata/macros.py

@@ -134,21 +134,22 @@ class MacrosGuide(GuideSheet):
 Macros allow you to bind a command sequence to a keystroke or longname, to replay when that keystroke is pressed or the command is executed by longname.
 
 The basic usage is:
-    1. Press `m` (macro-record) to begin recording the macro.
-    2. Go through the commands you wish to record.
-    3. Then type `m` again to complete the recording, and prompt for the keystroke or longname to bind it to.
+    1. `m` (`macro-record`) to begin recording the macro.
+    2. Execute a series of commands.
+    3. `m` again to complete the recording, and prompt for the keystroke or longname to bind it to.
 
 The macro will then be executed everytime the provided keystroke or longname are used. Note: the Alt+keys and the function keys are left unbound; overriding other keys may conflict with existing bindings, now or in the future.
 
 Executing a macro will the series of commands starting on the current row and column on the current sheet.
 
 # The Macros Sheet
 
-Use `gm` (`macro-sheet`) to open an index of existing macros.
+- `gm` (`macro-sheet`) to open an index of existing macros.
 
-Use `d` to mark macros for deletion. Use `z Ctrl+S` to then commit any changes.
+- `d` to mark macros for deletion.
+- `z Ctrl+S` to then commit any changes.
+- `Enter` to open the macro in the current row, and view the series of commands composing it.'''
 
-`Enter` to open the macro in the current row, and you can view the series of commands composing it.'''
 
 
 Sheet.addCommand('m', 'macro-record', 'vd.cmdlog.startMacro()', 'record macro')