add directive, update docs

hanjinliu · Jan 9, 2023 · ccfa5d3 · ccfa5d3
1 parent 2693dfb
commit ccfa5d3
Show file tree

Hide file tree

Showing 26 changed files with 195 additions and 93 deletions.
diff --git a/rst/_static/font.css b/rst/_static/font.css
@@ -1,7 +1,5 @@
 .gray {color: gray;}
 
-.grey {color: gray;}
-
 .silver {color: silver;}
 
 .white {color: white;}
@@ -31,3 +29,26 @@
 .navy {color: navy;}
 
 .purple {color: purple;}
+
+.kbd {
+    background-color: #f1f1f1;
+    border: 1px solid #ccc;
+    border-radius: 3px;
+    box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 2px #fff inset;
+    color: #444;
+    display: inline-block;
+    font-size: 0.85em;
+    font-weight: 700;
+    line-height: 1;
+    padding: 0.2em 0.4em;
+    white-space: nowrap;
+}
+
+.menu {
+    background-color: #f1f1f1;
+    border: 1px solid #ccc;
+    box-shadow: 0 1px 0 rgba(0, 0, 0, 0.2), 0 0 0 1px #fff inset;
+    font-size: 0.85em;
+    padding: 0.2em 0.4em;
+    white-space: nowrap;
+}
diff --git a/rst/fig/cell_labels.png b/rst/fig/cell_labels.png
diff --git a/rst/fig/colormap.png b/rst/fig/colormap.png
diff --git a/rst/fig/colormap_interpolate.png b/rst/fig/colormap_interpolate.png
diff --git a/rst/fig/column_filter.png b/rst/fig/column_filter.png
diff --git a/rst/fig/command_palette.png b/rst/fig/command_palette.png
diff --git a/rst/fig/dock_with_table_data_annotation.png b/rst/fig/dock_with_table_data_annotation.png
diff --git a/rst/fig/edit_cell.png b/rst/fig/edit_cell.png
diff --git a/rst/fig/formatter.png b/rst/fig/formatter.png
diff --git a/rst/fig/generate_figs.py b/rst/fig/generate_figs.py
@@ -6,6 +6,21 @@
 
 REG = FunctionRegistry(Path(__file__).parent)
 
+@REG.register
+def table():
+    viewer = TableViewer()
+    table = viewer.add_table({"A": [1, 2, 3], "B": [4, 5, 6]}, name="table name")
+    viewer.native.setMinimumSize(1, 1)
+    viewer.resize(120, 180)
+    return table
+
+@REG.register
+def spreadsheet():
+    viewer = TableViewer()
+    sheet = viewer.add_spreadsheet([["2", "t"], ["3", "u"]])
+    viewer.native.setMinimumSize(1, 1)
+    viewer.resize(120, 180)
+    return sheet
 
 @REG.register
 def edit_cell():
@@ -134,6 +149,15 @@ def column_filter():
     sheet.proxy.filter("A > 5")
     return viewer
 
+@REG.register
+def command_palette():
+    viewer = TableViewer()
+    viewer.add_spreadsheet()
+    viewer.resize(100, 100)
+    cmds.window.show_command_palette(viewer)
+    cmdp = viewer.native._command_palette.get_widget(viewer.native)
+    cmdp._line.setText("cop")
+    return viewer
 
 if __name__ == "__main__":
     REG.run_all()
diff --git a/rst/fig/spreadsheet.png b/rst/fig/spreadsheet.png
diff --git a/rst/fig/table.png b/rst/fig/table.png
diff --git a/rst/fig/tile_tables.png b/rst/fig/tile_tables.png
diff --git a/rst/fig/validator.png b/rst/fig/validator.png
diff --git a/rst/font.rst b/rst/font.rst
@@ -13,3 +13,5 @@
 .. role:: aqua
 .. role:: blue
 .. role:: purple
+.. role:: kbd
+.. role:: menu
diff --git a/rst/index.rst b/rst/index.rst
@@ -20,7 +20,7 @@ Tables
 ------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ./main/selections
    ./main/sort_filter
@@ -32,7 +32,7 @@ Cooperate with Other Widgets
 ----------------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ./main/integrate_custom_widgets
    ./main/non_mainwindow

diff --git a/rst/main/columnwise_settings.rst b/rst/main/columnwise_settings.rst
@@ -2,6 +2,8 @@
 Column-wise Settings
 ====================
 
+.. include:: ../font.rst
+
 Tables are composed of several columns with different data types. There are some settings
 that can be applied to each column individually, for better visualizing the data and safely
 editing the data.
@@ -131,7 +133,7 @@ Set Colormaps in GUI
 --------------------
 
 Some basic colormaps are available in the right-click context menu of the columns,
-such as ``Color > Set background colormap``.
+such as :menu:`Color > Set background colormap`.
 
 Validator
 =========
@@ -221,7 +223,7 @@ Set Formatter in GUI
 --------------------
 
 Some basic formatters are available in the right-click context menu of the columns,
-such as ``Formatter > Set text formatter``. You'll see a preview of the column in
+such as :menu:`Formatter > Set text formatter`. You'll see a preview of the column in
 the dialog.
 
 Typing Spreadsheet
@@ -232,8 +234,8 @@ because a spreadsheet is a string-based table data in general. This characterist
 raises a problem of data type. This drawback is especially important when you want
 to use data types such as ``datetime64`` or ``category``.
 
-To solve this problem, ``SpreadSheet`` implements a typing system on each column.
-You can tag any data types supported by ``pandas`` to each column, and optionally
+To solve this problem, :class:`SpreadSheet` implements a typing system on each column.
+You can tag any data types supported by :class:`pandas` to each column, and optionally
 set validator functions appropriate for the data types.
 
 .. code-block:: python
@@ -263,4 +265,4 @@ set validator functions appropriate for the data types.
     dtype: object
 
 You can also set dtypes from GUI. Right-click the column header and select
-``Column dtype``.
+:menu:`Column dtype`.
diff --git a/rst/main/integrate_custom_widgets.rst b/rst/main/integrate_custom_widgets.rst
@@ -6,6 +6,8 @@ Integrate Custom Widgets
     :local:
     :depth: 1
 
+.. include:: ../font.rst
+
 There are several places to integrate your custom widgets to :mod:`tabulous` viewer.
 
 Dock Widget Area
@@ -51,14 +53,14 @@ Basic usage
 
 .. note::
 
-    In ``napari``, you can use such as ``ImageData`` as an alias for ``np.ndarray`` type,
-    while inform ``@magicgui`` that the data you want is the array stored in an ``Image``
-    layer, or returned array should be added as a new ``Image`` layer. ``tabulous`` uses
-    the same strategy to recover a ``pd.DataFrame`` from the table list or send a new one
+    In :mod:`napari``, you can use such as :mod:`ImageData` as an alias for :class:`np.ndarray` type,
+    while inform ``@magicgui`` that the data you want is the array stored in an :class:`Image`
+    layer, or returned array should be added as a new :class:`Image` layer. :mod:`tabulous` uses
+    the same strategy to recover a :class:`pd.DataFrame` from the table list or send a new one
     to the viewer.
 
 :class:`TableData` type is an alias of :class:`pd.DataFrame`. Arguments annotated by this
-type will be interpreted as a combobox of table data by ``magicgui``.
+type will be interpreted as a combobox of table data by :mod:`magicgui`.
 
 .. code-block:: python
 
@@ -82,7 +84,7 @@ Table Side Area
 Every table has a side area that can be used to add table-specific widgets or show
 table-specific information.
 
-Custom Qt widgets or ``magicgui`` widgets can be added to the side area using
+Custom Qt widgets or :mod:`magicgui` widgets can be added to the side area using
 :meth:`add_side_widget` method.
 
 .. code-block:: python
@@ -109,7 +111,7 @@ There are built-in widgets that uses the table side area by default.
 1. Undo stack widget
 
     Undo/redo is implemented for each table. You can see the registered operations in a list
-    view in the side area. You can open it by pressing ``Ctrl+H``.
+    view in the side area. You can open it by pressing :kbd:`Ctrl+H`.
 
 2. Plot canvas
 

diff --git a/rst/main/non_mainwindow.rst b/rst/main/non_mainwindow.rst
@@ -2,7 +2,7 @@
 Use Non-main Window Table Viewers
 =================================
 
-Aiming at better extensibility, ``tabulous`` is designed to allow many different types of
+Aiming at better extensibility, :mod:`tabulous` is designed to allow many different types of
 integration to external packages.
 
 .. contents:: Contents
@@ -12,8 +12,8 @@ integration to external packages.
 Use TableViewer in Your Qt Widget
 =================================
 
-If you plan to use a table viewer as a child of another ``QWidget``, you can use a non-main
-window version of it. The ``native`` property returns the Qt backend widget.
+If you plan to use a table viewer as a child of another :class:`QWidget`, you can use a non-main
+window version of it. The :attr:`native` property returns the Qt backend widget.
 
 .. code-block:: python
 
@@ -28,23 +28,24 @@ window version of it. The ``native`` property returns the Qt backend widget.
 
 .. note::
 
-    A benefit of using ``tabulous`` is that a table widget usually takes too much space but this
-    problem can be solve by popup view of tables in ``tabulous``. See :doc:`table_view_mode` for
+    A benefit of using :mod:`tabulous` is that a table widget usually takes too much space but this
+    problem can be solve by popup view of tables in :mod:`tabulous`. See :doc:`table_view_mode` for
     more detail.
 
 .. note::
 
     To avoid conflicting with the main widget, the non-main-window version of table viewer has
-    some restriction. For instance, embedded console does not open with shortcut ``Ctrl+Shift+C``
+    some restriction. For instance, embedded console does not open with shortcut :kbd:`Ctrl+Shift+C`
     so you have to programmatically open it by ``viewer.console.visible = True``.
 
 
 Use TableViewer with magicgui
 =============================
 
-If you want to use a `magicgui <https://github.com/pyapp-kit/magicgui>`_ version of it, you can
-use ``MagicTableViewer``. ``MagicTableViewer`` is a subclass of ``TableViewerWidget`` and
-``magicgui.widgets.Widget`` so it is compatible with all the ``magicgui`` functionalities.
+If you want to use a `magicgui <https://github.com/pyapp-kit/magicgui>`_ version of it,
+you can use :class:`MagicTableViewer`. :class:`MagicTableViewer`` is a subclass of
+:class:`TableViewerWidget` and :class:`magicgui.widgets.Widget` so it is compatible with
+all the :mod:`magicgui` functionalities.
 
 In following simple example you can load a table data from a file.
 
@@ -63,7 +64,7 @@ In following simple example you can load a table data from a file.
 
     container.show()
 
-``MagicTableViewer`` can also easily be used with `magic-class <https://github.com/hanjinliu/magic-class>`_.
+:class:`MagicTableViewer` can also easily be used with `magic-class <https://github.com/hanjinliu/magic-class>`_.
 Following example does similar thing as the one above.
 
 .. code-block:: python

diff --git a/rst/main/quickstart.rst b/rst/main/quickstart.rst
@@ -6,10 +6,12 @@ Quickstart
     :local:
     :depth: 1
 
+.. include:: ../font.rst
+
 Open A Table Viewer
 ===================
 
-The main window of ``tabulous`` is a ``TableViewer`` instance.
+The main window of :mod:`tabulous` is a :class:`TableViewer` instance.
 
 .. code-block:: python
 
@@ -29,7 +31,7 @@ You can also read table data from files to create a viewer.
     # Read a Excel file and add all the sheets to the viewer.
     viewer = tbl.read_excel("path/to/data.xlsx")
 
-If virtual environment (such as ``conda``) is used, you can use ``tabulous`` command to launch
+If virtual environment (such as ``conda``) is used, you can use :mod:`tabulous` command to launch
 a viewer.
 
 .. code-block:: bash
@@ -41,30 +43,30 @@ a viewer.
 Open an Interpreter
 ===================
 
-``tabulous`` viewer has an embedded Python interpreter console. It is not visible by default
+:mod:`tabulous` viewer has an embedded Python interpreter console. It is not visible by default
 but you can show it in several ways.
 
 .. |toggle_console| image:: ../../tabulous/_qt/_icons/toggle_console.svg
   :width: 20em
 
 1. Set :attr:`visible` property of :attr:`console` interface to ``True``:
    ``>>> viewer.conosole.visible = True``
-2. Activate keyboard shortcut ``Ctrl+Shift+C``.
-3. Click the |toggle_console| tool button in the "Analysis" tab of the toolbar.
+2. Activate keyboard shortcut :kbd:`Ctrl+Shift+C`.
+3. Click the |toggle_console| tool button in the the toolbar.
 
 In ``tabulous`` viewer there are additional keybindings.
 
-- ``Ctrl + Shift + ↑``: Set console floating.
-- ``Ctrl + Shift + ↓``: Dock console.
+- :kbd:`Ctrl+Shift+↑`: Set console floating.
+- :kbd:`Ctrl+Shift+↓`: Dock console.
 
 Use Tables
 ==========
 
 In :mod:`tabulous`, table data is handled based on :mod:`pandas`.
 A :class:`TableViewer` instance has several methods that add :class:`DataFrame` to the viewer.
 
-1. :meth:`add_table` ... add a table data as a ``Table`` object.
-2. :meth:`add_spreadsheet` ... add a table data as a ``SpreadSheet`` object.
+1. :meth:`add_table` ... add a table data as a :class:`Table` object.
+2. :meth:`add_spreadsheet` ... add a table data as a :class:`SpreadSheet` object.
 
 Table
 -----
@@ -93,6 +95,8 @@ the viewer using :meth:`add_table` method.
 
     Table<'table name'>
 
+.. image:: ../fig/table.png
+
 .. note::
 
     The newly added table is stored in :attr:`tables` property of the viewer in a :class:`list` like
@@ -118,16 +122,16 @@ You have to pass ``editable=True`` or set the :attr:`editable` property to make
     # or set the property
     table.editable = True
 
-Table data is available in ``data`` property. You can also update the table data by directly
-setting the ``data`` property.
+Table data is available in :attr:`data` property. You can also update the table data by directly
+setting the :attr:`data` property.
 
 .. code-block:: python
 
     df = table.data  # get the table data as a DataFrame
     table.data = df2  # set a new table data
 
-The selected range of data is available in ``selections`` property. You can also
-programmatically set table selections via ``selections`` property. Since table selections are
+The selected range of data is available in :attr:`selections` property. You can also
+programmatically set table selections via :attr:`selections` property. Since table selections are
 multi-selection, this property takes a ``list`` of slicable objects.
 
 .. code-block:: python
@@ -144,21 +148,16 @@ See :doc:`selections` for more details.
 SpreadSheet
 -----------
 
-A ``SpreadSheet`` behaves more like Excel or Google Spreadsheet.
+A :class:`SpreadSheet` behaves more like Excel or Google Spreadsheet.
 
 - It stores a copy of an input :class:`DataFrame` as "string" types.
 - It is editable by default and the input value will not be checked.
 - Shape of table is unlimited (as far as it is not too large).
-- The data type is inferred by ``pd.read_csv`` when it is obtained by ``data`` property.
+- The data type is inferred by :meth:`pd.read_csv` when it is obtained by :attr:`data` property.
 
 For instance, if you manually edited the cells
 
-===  ===  ===
- ..    A  B
-===  ===  ===
-  0    2  t
-  1    3  u
-===  ===  ===
+.. image:: ../fig/spreadsheet.png
 
 then you'll get following :class:`DataFrame`.
 
@@ -187,7 +186,7 @@ A spreadsheet can be added to the viewer by :meth:`add_spreadsheet` method.
 
     SpreadSheet<'sheet'>
 
-Since a :class:`SpreadSheet`` is easily editable, it is reasonable to add an empty spreadsheet to
+Since a :class:`SpreadSheet` is easily editable, it is reasonable to add an empty spreadsheet to
 the viewer.
 
 .. code-block:: python
@@ -224,7 +223,7 @@ Key combo
 :mod:`tabulous` supports many keyboard shortcuts including key combo.
 
 All the global key map is listed in a widget that will be shown when you press
-``Ctrl+K, Shift+?`` key combo.
+:kbd:`Ctrl+K ⇒ Shift+?` key combo.
 
 :attr:`keymap` is the key map registry object of table viewers. You can use :meth:`bind_key`
 to register custom key combo.
@@ -251,5 +250,7 @@ Command palette
 
 .. versionadded:: 0.4.0
 
-``Ctrl+Shift+P`` or ``F1`` opens a command palette widget. You can search for a variety of
+:kbd:`Ctrl+Shift+P` or :kbd:`F1` opens a command palette widget. You can search for a variety of
 registered commands.
+
+.. image:: ../fig/command_palette.png