Docs update (fixes iommirocks#703)

Author: boxed

docs/api.rst

@@ -28,6 +28,8 @@ API Reference
    Menu
    MenuItem
    Page
+   Panel
+   PanelCol
    Part
    Query
    QueryAutoConfig

docs/test_doc_cookbook_forms.py

@@ -1378,6 +1378,8 @@ def log_and_write(field, instance, value, **kwargs):
 def test_layout_with_panels():
     # language=rst
     """
+    .. _complex-layouts-forms:
+
     How do I make complex layouts for forms?
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/test_doc_cookbook_tables.py

@@ -1585,6 +1585,8 @@ def test_how_do_i_set_an_empty_message():
 def test_row_layout_with_panels(small_discography):
     # language=rst
     """
+    .. _complex-layouts-tables:
+
     How do I make complex layouts for table rows?
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/test_doc_fragments.py

@@ -5,7 +5,7 @@
 Fragments
 ---------
 
-If you are just using iommi's built in components like `Form` and `Table`, you won't need to use `Fragment` directly. `Fragment` is a class that is used to compose HTML tags in a way that is later :ref:`refinable`. The most basic example of this is the :ref:`h_tag <h_tag>` of a form or table. A `Fragment` has :ref:`attrs <attributes>`, :ref:`template` and :ref:`tag` configuration:
+If you are just using iommi's built in components like `Form` and `Table`, you won't need to use `Fragment` directly. `Fragment` is a class that is used to compose HTML tags in a way that is later refinable. The most basic example of this is the :ref:`h_tag <h_tag>` of a form or table. A `Fragment` has :ref:`attrs <attributes>`, :ref:`template` and :ref:`tag` configuration:
 """
 from docs.models import Artist
 from iommi.docs import show_output

docs/test_doc_main_menu.py

@@ -20,6 +20,8 @@ def fake_view():
 def test_base(settings, medium_discography):
     # language=rst
     """
+    .. _mainmenu:
+
     Main menu
     ~~~~~~~~~
 

iommi/docs.py

@@ -31,6 +31,7 @@
 from iommi.refinable import (
     EvaluatedRefinable,
     is_refinable_function,
+    RefinableObject,
     SpecialEvaluatedRefinable,
 )
 from iommi.shortcut import (
@@ -119,6 +120,8 @@ def get_default_classes():
         iommi.Page,
         iommi.Menu,
         iommi.MenuItem,
+        iommi.M,
+        iommi.MainMenu,
         iommi.Style,
         iommi.fragment.Header,
         iommi.Asset,
@@ -312,6 +315,8 @@ def auto_use(big_discography):
 
     if c.__base__ in classes:
         w(0, f'Base class: :doc:`{c.__base__.__name__}`')
+    elif c.__base__ is object:
+        pass
     else:
         w(0, f'Base class: `{c.__base__.__name__}`')
 
@@ -401,7 +406,7 @@ def default_description(v):
             cookbook_usages = uses_by_field.get(f'{c.__name__}.{refinable}', [])
             if cookbook_usages:
                 w(0, '')
-                w(0, f'Cookbook:')
+                w(0, 'Cookbook:')
                 for id_, title in cookbook_usages:
                     w(1, f':ref:`{id_}`')
                     w(0, '')
@@ -411,6 +416,16 @@ def default_description(v):
 
         w(0, '')
 
+    if not issubclass(c, RefinableObject):
+        section(3, 'Constructor arguments')
+
+        for k, v in inspect.signature(x.__init__).parameters.items():
+            if k == 'self':
+                continue
+            w(0, f'* `{k}`')
+
+        w(0, '')
+
     assert not defaults
 
     shortcuts = get_shortcuts_by_name(c)

iommi/main_menu.py

@@ -59,6 +59,11 @@ def path(path, view_or_list, name=None, kwargs=None):
 
 
 class MainMenu:
+    # language=rst
+    """
+    See the :ref:`MainMenu <mainmenu>` docs and the :ref:`MainMenu cookbook <cookbook-main-menu>`.
+    """
+
     @dispatch(
         items=EMPTY,
         attrs__style=EMPTY,
@@ -209,6 +214,11 @@ def own_evaluate_parameters(self):
 
 
 class M:
+    # language=rst
+    """
+    See the :ref:`MainMenu <mainmenu>` docs and the :ref:`MainMenu cookbook <cookbook-main-menu>`.
+    """
+
     @dispatch(
         items=EMPTY,
         attrs__style=EMPTY,

iommi/panel.py

@@ -14,7 +14,9 @@
 
 class PanelCol(Fragment):
     """
-    generates div.col - for wrapping all children of Panel.row
+    Generates `div.col` - for wrapping all children of `Panel.row`.
+
+    See :ref:`the forms cookbook <complex-layouts-forms>` and :ref:`the table cookbook <complex-layouts-tables>`.
     """
 
     @with_defaults(
@@ -30,7 +32,7 @@ def __init__(self, **kwargs):
 
 class Panel(Fragment):
     """
-    wrappers for defining Form.layout
+    Class used to define form and table row layouts. See :ref:`the forms cookbook <complex-layouts-forms>` and :ref:`the table cookbook <complex-layouts-tables>`.
     """
     _parent_form = Refinable()  # Form|None
     _parent_table = Refinable()  # Table|None