api docs (#2240)

* api docs

* more docstrings

* logs

* docs shakeup

* fix notes, added intro to all apis

* Remove defaults to

* add note to events

* note

* use fira code

docs/_templates/python/material/_base/class.html

@@ -13,7 +13,9 @@
     {% set show_full_path = config.show_object_full_path %}
   {% endif %}
 
-  {% if not root or config.show_root_heading %}
+
+
+  {% if 1 %}
 
     {% filter heading(heading_level,
         role="class",
@@ -34,7 +36,7 @@
         <code>{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</code>
       {% endif %}
 
-      {% with labels = class.labels %}
+      {% with labels = ['class'] %}
         {% include "labels.html" with context %}
       {% endwith %}
 
@@ -43,11 +45,10 @@
     {% if config.separate_signature and config.merge_init_into_class %}
       {% if "__init__" in class.members %}
         {% with function = class.members["__init__"] %}
-          {% filter highlight(language="python", inline=False) %}
-class {% filter format_signature(config.line_length) %}
-              {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
-              {% include "signature.html" with context %}
-            {% endfilter %}
+          {% filter highlight(language="python", inline=False) -%}
+            def {% filter format_signature(config.line_length) %}
+__init__{% include "signature.html" with context %}
+            {% endfilter %}:
           {% endfilter %}
         {% endwith %}
       {% endif %}

docs/_templates/python/material/_base/docstring/admonition.html

@@ -0,0 +1,5 @@
+{{ log.debug("Rendering admonition") }}
+<details class="{{ section.value.kind }}" open>
+  <summary>{{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }}</summary>
+  {{ section.value.contents|convert_markdown(heading_level, html_id) }}
+</details>

docs/_templates/python/material/_base/function.html

@@ -29,8 +29,7 @@
           {% include "signature.html" with context %}
         {% endfilter %}
       {% endif %}
-
-      {% with labels = function.labels %}
+      {% with labels = function.labels or [(function.parameters._parameters_list and function.parameters._parameters_list[0].name == 'self') and 'method' or 'function'] %}
         {% include "labels.html" with context %}
       {% endwith %}
 
@@ -41,7 +40,7 @@
 def {% filter format_signature(config.line_length) %}
           {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}
           {% include "signature.html" with context %}
-        {% endfilter %}
+        {% endfilter %}:
       {% endfilter %}
     {% endif %}
 

docs/_templates/python/material/_base/signature.html

@@ -10,14 +10,14 @@
 
     (
       {%- for parameter in function.parameters -%}
-        {%- if parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%}
+        {%- if 1 -%}
 
           {%- if parameter.kind.value == "positional-only" -%}
             {%- set ns.has_pos_only = True -%}
           {%- else -%}
             {%- if ns.has_pos_only and ns.render_pos_only_separator -%}
               {%- set ns.render_pos_only_separator = False %}/, {% endif -%}
-            {%- if parameter.kind.value == "keyword-only" -%}
+          {%- if parameter.kind.value == "keyword-only" -%}
               {%- if ns.render_kw_only_separator -%}
                 {%- set ns.render_kw_only_separator = False %}*, {% endif -%}
             {%- endif -%}

docs/api/button.md

@@ -1,3 +0,0 @@
-::: textual.widgets.Button
-::: textual.widgets._button.ButtonVariant
-::: textual.widgets._button.InvalidButtonVariant

docs/api/checkbox.md

@@ -1 +0,0 @@
-::: textual.widgets.Checkbox

docs/api/data_table.md

@@ -1 +0,0 @@
-::: textual.widgets.DataTable

docs/api/directory_tree.md

@@ -1 +0,0 @@
-::: textual.widgets.DirectoryTree

docs/api/footer.md

@@ -1 +0,0 @@
-::: textual.widgets.Footer

docs/api/header.md

@@ -1 +0,0 @@
-::: textual.widgets.Header

docs/api/input.md

@@ -1 +0,0 @@
-::: textual.widgets.Input

docs/api/label.md

@@ -1 +0,0 @@
-::: textual.widgets.Label

docs/api/list_item.md

@@ -1 +0,0 @@
-::: textual.widgets.ListItem

docs/api/list_view.md

@@ -1 +0,0 @@
-::: textual.widgets.ListView

docs/api/loading_indicator.md

@@ -1 +0,0 @@
-::: textual.widgets.LoadingIndicator

docs/api/logger.md

@@ -0,0 +1 @@
+::: textual.Logger

docs/api/markdown.md

@@ -1 +0,0 @@
-::: textual.widgets.Markdown

docs/api/markdown_viewer.md

@@ -1 +0,0 @@
-::: textual.widgets.MarkdownViewer

docs/api/message_pump.md

@@ -1,5 +1 @@
-A message pump is a class that processes messages.
-
-It is a base class for the `App`, `Screen`, and `Widget` classes.
-
 ::: textual.message_pump

docs/api/option_list.md

@@ -1,3 +0,0 @@
-::: textual.widgets.OptionList
-::: textual.widgets._option_list.Option
-::: textual.widgets._option_list.Separator

docs/api/placeholder.md

@@ -1,2 +0,0 @@
-::: textual.widgets.Placeholder
-::: textual.widgets._placeholder.PlaceholderVariant

docs/api/radiobutton.md

@@ -1 +0,0 @@
-::: textual.widgets.RadioButton

docs/api/radioset.md

@@ -1 +0,0 @@
-::: textual.widgets.RadioSet

docs/api/static.md

@@ -1 +0,0 @@
-::: textual.widgets.Static

docs/api/switch.md

@@ -1 +0,0 @@
-::: textual.widgets.Switch

docs/api/tabbed_content.md

@@ -1,2 +0,0 @@
-::: textual.widgets.TabbedContent
-::: textual.widgets.TabPane

docs/api/tabs.md

@@ -1,2 +0,0 @@
-::: textual.widgets.Tab
-::: textual.widgets.Tabs

docs/api/text_log.md

@@ -1 +0,0 @@
-::: textual.widgets.TextLog

docs/api/toggle_button.md

@@ -1 +0,0 @@
-::: textual.widgets._toggle_button.ToggleButton

docs/api/tree.md

@@ -1,4 +0,0 @@
-::: textual.widgets.Tree
-::: textual.widgets._tree.TreeNode
-::: textual.widgets._tree.NodeID
-::: textual.widgets._tree.TreeDataType

docs/api/welcome.md

@@ -1 +0,0 @@
-::: textual.widgets.Welcome

docs/api/work.md

@@ -1 +1,2 @@
+
 ::: textual.work

docs/blog/posts/release0-11-0.md

@@ -38,7 +38,7 @@ Additionally there are new [update_cell][textual.widgets.DataTable.update_cell]
 
 ## Tree control
 
-The [Tree](../../api/tree.md) widget has grown a few methods to programmatically expand, collapse and toggle tree nodes.
+The [Tree](../../widgets/tree.md) widget has grown a few methods to programmatically expand, collapse and toggle tree nodes.
 
 ## Breaking changes
 

docs/stylesheets/custom.css

@@ -43,9 +43,14 @@ body[data-md-color-primary="black"] .excalidraw svg rect {
   border: 0;
 }
 
+.doc-object code {
+  font-family: "Fira Code", "SFMono-Regular", Consolas, "Courier New", Courier,
+    monospace;
+}
+
 
 /* Indentation. */
-div.doc-contents:not(.first) .doc-contents {
+div.doc-contents:not(.first) {
   padding-left: 25px;
   border-left: .05rem solid var(--md-typeset-table-color);
 }

docs/widgets/_template.md

@@ -61,6 +61,13 @@ The WIDGET widget provides the following component classes:
 
 ## See also
 
-- [WIDGET](../api/WIDGET.md) code reference.
 - Another related API.
 - Something else useful.
+
+
+---
+
+
+::: textual.widgets.WIDGET
+    options:
+      heading_level: 2

docs/widgets/button.md

@@ -39,12 +39,15 @@ Clicking any of the non-disabled buttons in the example app below will result in
 
 ## Messages
 
-### ::: textual.widgets.Button.Pressed
+- [Button.Pressed][textual.widgets.Button.Pressed]
 
 ## Additional Notes
 
 * The spacing between the text and the edges of a button are due to border, _not_ padding. To create a button with zero visible padding, use the `border: none;` declaration.
 
-## See Also
+---
 
-* [Button](../api/button.md) code reference
+
+::: textual.widgets.Button
+    options:
+      heading_level: 2

docs/widgets/checkbox.md

@@ -54,8 +54,12 @@ The checkbox widget provides the following component classes:
 
 ## Messages
 
-### ::: textual.widgets.Checkbox.Changed
+- [Checkbox.Changed][textual.widgets.Checkbox.Changed]
 
-## See Also
 
-- [Checkbox](../api/checkbox.md) code reference
+---
+
+
+::: textual.widgets.Checkbox
+    options:
+      heading_level: 2

docs/widgets/content_switcher.md

@@ -46,11 +46,14 @@ When the user presses the "Markdown" button the view is switched:
 
 ## Reactive Attributes
 
-| Name      | Type            | Default | Description                                                          |
-|-----------|-----------------|---------|----------------------------------------------------------------------|
+| Name      | Type            | Default | Description                                                             |
+| --------- | --------------- | ------- | ----------------------------------------------------------------------- |
 | `current` | `str` \| `None` | `None`  | The ID of the currently-visible child. `None` means nothing is visible. |
 
 
-## See Also
+---
 
-* [ContentSwitcher][textual.widgets.ContentSwitcher] code reference
+
+::: textual.widgets.ContentSwitcher
+    options:
+      heading_level: 2

docs/widgets/data_table.md

@@ -36,19 +36,13 @@ The example below populates a table with CSV data.
 
 ## Messages
 
-### ::: textual.widgets.DataTable.CellHighlighted
-
-### ::: textual.widgets.DataTable.CellSelected
-
-### ::: textual.widgets.DataTable.RowHighlighted
-
-### ::: textual.widgets.DataTable.RowSelected
-
-### ::: textual.widgets.DataTable.ColumnHighlighted
-
-### ::: textual.widgets.DataTable.ColumnSelected
-
-### ::: textual.widgets.DataTable.HeaderSelected
+- [DataTable.CellHighlighted][textual.widgets.DataTable.CellHighlighted]
+- [DataTable.CellSelected][textual.widgets.DataTable.CellSelected]
+- [DataTable.RowHighlighted][textual.widgets.DataTable.RowHighlighted]
+- [DataTable.RowSelected][textual.widgets.DataTable.RowSelected]
+- [DataTable.ColumnHighlighted][textual.widgets.DataTable.ColumnHighlighted]
+- [DataTable.ColumnSelected][textual.widgets.DataTable.ColumnSelected]
+- [DataTable.HeaderSelected][textual.widgets.DataTable.HeaderSelected]
 
 ## Bindings
 
@@ -68,6 +62,9 @@ The data table widget provides the following component classes:
       show_root_heading: false
       show_root_toc_entry: false
 
-## See Also
+---
 
-* [DataTable][textual.widgets.DataTable] code reference
+
+::: textual.widgets.DataTable
+    options:
+      heading_level: 2

docs/widgets/directory_tree.md

@@ -36,7 +36,7 @@ and directories:
 
 ## Messages
 
-### ::: textual.widgets.DirectoryTree.FileSelected
+- [DirectoryTree.FileSelected][textual.widgets.DirectoryTree.FileSelected]
 
 ## Reactive Attributes
 
@@ -57,5 +57,13 @@ The directory tree widget provides the following component classes:
 
 ## See Also
 
-* [DirectoryTree][textual.widgets.DirectoryTree] code reference
 * [Tree][textual.widgets.Tree] code reference
+
+
+
+---
+
+
+::: textual.widgets.DirectoryTree
+    options:
+      heading_level: 2

docs/widgets/footer.md

@@ -46,6 +46,10 @@ The footer widget provides the following component classes:
 * You can prevent keybindings from appearing in the footer by setting the `show` argument of the `Binding` to `False`.
 * You can customize the text that appears for the key itself in the footer using the `key_display` argument of `Binding`.
 
-## See Also
 
-* [Footer](../api/footer.md) code reference
+---
+
+
+::: textual.widgets.Footer
+    options:
+      heading_level: 2

docs/widgets/header.md

@@ -30,6 +30,9 @@ The example below shows an app with a `Header`.
 
 This widget sends no messages.
 
-## See Also
+---
 
-* [Header](../api/header.md) code reference
+
+::: textual.widgets.Header
+    options:
+      heading_level: 2

docs/widgets/input.md

@@ -32,9 +32,8 @@ The example below shows how you might create a simple form using two `Input` wid
 
 ## Messages
 
-### ::: textual.widgets.Input.Changed
-
-### ::: textual.widgets.Input.Submitted
+- [Input.Changed][textual.widgets.Input.Changed]
+- [Input.Submitted][textual.widgets.Input.Submitted]
 
 ## Bindings
 
@@ -58,6 +57,9 @@ The input widget provides the following component classes:
 
 * The spacing around the text content is due to border. To remove it, set `border: none;` in your CSS.
 
-## See Also
+---
 
-* [Input](../api/input.md) code reference
+
+::: textual.widgets.Input
+    options:
+      heading_level: 2

docs/widgets/label.md

@@ -30,6 +30,9 @@ This widget has no reactive attributes.
 
 This widget sends no messages.
 
-## See Also
+---
 
-* [Label](../api/label.md) code reference
+
+::: textual.widgets.Label
+    options:
+      heading_level: 2

docs/widgets/list_item.md

@@ -26,16 +26,19 @@ of multiple `ListItem`s. The arrow keys can be used to navigate the list.
 ## Reactive Attributes
 
 | Name          | Type   | Default | Description                          |
-|---------------|--------|---------|--------------------------------------|
+| ------------- | ------ | ------- | ------------------------------------ |
 | `highlighted` | `bool` | `False` | True if this ListItem is highlighted |
 
 
 #### Attributes
 
 | attribute | type       | purpose                     |
-|-----------|------------|-----------------------------|
+| --------- | ---------- | --------------------------- |
 | `item`    | `ListItem` | The item that was selected. |
 
-## See Also
+---
 
-* [ListItem](../api/list_item.md) code reference
+
+::: textual.widgets.ListItem
+    options:
+      heading_level: 2

docs/widgets/list_view.md

@@ -37,9 +37,8 @@ The example below shows an app with a simple `ListView`.
 
 ## Messages
 
-### ::: textual.widgets.ListView.Highlighted
-
-### ::: textual.widgets.ListView.Selected
+- [ListView.Highlighted][textual.widgets.ListView.Highlighted]
+- [ListView.Selected][textual.widgets.ListView.Selected]
 
 ## Bindings
 
@@ -50,6 +49,9 @@ The list view widget defines the following bindings:
       show_root_heading: false
       show_root_toc_entry: false
 
-## See Also
+---
 
-* [ListView](../api/list_view.md) code reference
+
+::: textual.widgets.ListView
+    options:
+      heading_level: 2

docs/widgets/loading_indicator.md

@@ -28,7 +28,9 @@ LoadingIndicator {
     ```python
     --8<-- "docs/examples/widgets/loading_indicator.py"
     ```
+---
 
-## See Also
 
-* [LoadingIndicator](../api/loading_indicator.md) code reference
+::: textual.widgets.LoadingIndicator
+    options:
+      heading_level: 2

docs/widgets/markdown.md

@@ -29,14 +29,20 @@ The following example displays Markdown from a string.
 
 ## Messages
 
-### ::: textual.widgets.Markdown.TableOfContentsUpdated
-
-### ::: textual.widgets.Markdown.TableOfContentsSelected
-
-### ::: textual.widgets.Markdown.LinkClicked
+- [Markdown.TableOfContentsUpdated][textual.widgets.Markdown.TableOfContentsUpdated]
+- [Markdown.TableOfContentsSelected][textual.widgets.Markdown.TableOfContentsSelected]
+- [Markdown.LinkClicked][textual.widgets.Markdown.LinkClicked]
 
 
 ## See Also
 
-* [Markdown][textual.widgets.Markdown] code reference
+
 * [MarkdownViewer][textual.widgets.MarkdownViewer] code reference
+
+
+---
+
+
+::: textual.widgets.Markdown
+    options:
+      heading_level: 2

docs/widgets/markdown_viewer.md

@@ -35,5 +35,13 @@ The following example displays Markdown from a string and a Table of Contents.
 
 ## See Also
 
-* [MarkdownViewer][textual.widgets.MarkdownViewer] code reference
 * [Markdown][textual.widgets.Markdown] code reference
+
+
+
+---
+
+
+::: textual.widgets.MarkdownViewer
+    options:
+      heading_level: 2

docs/widgets/option_list.md

@@ -82,14 +82,13 @@ tables](https://rich.readthedocs.io/en/latest/tables.html):
 ## Reactive Attributes
 
 | Name          | Type            | Default | Description                                                               |
-|---------------|-----------------|---------|---------------------------------------------------------------------------|
+| ------------- | --------------- | ------- | ------------------------------------------------------------------------- |
 | `highlighted` | `int` \| `None` | `None`  | The index of the highlighted option. `None` means nothing is highlighted. |
 
 ## Messages
 
-### ::: textual.widgets.OptionList.OptionHighlighted
-
-### ::: textual.widgets.OptionList.OptionSelected
+- [OptionList.OptionHighlight][textual.widgets.OptionList.OptionHighlighted]
+- [OptionList.OptionSelected][textual.widgets.OptionList.OptionSelected]
 
 Both of the messages above inherit from this common base, which makes
 available the following properties relating to the `OptionList` and the
@@ -122,6 +121,8 @@ The option list provides the following component classes:
       show_root_heading: false
       show_root_toc_entry: false
 
-## See Also
 
-* [OptionList][textual.widgets.OptionList] code reference
+
+::: textual.widgets.OptionList
+    options:
+      heading_level: 2

docs/widgets/placeholder.md

@@ -34,15 +34,18 @@ The example below shows each placeholder variant.
 
 ## Reactive Attributes
 
-| Name       | Type   | Default     | Description                                        |
-| ---------- | ------ | ----------- | -------------------------------------------------- |
-| `variant`  | `str`  | `"default"` | Styling variant. One of `default`, `size`, `text`. |
+| Name      | Type  | Default     | Description                                        |
+| --------- | ----- | ----------- | -------------------------------------------------- |
+| `variant` | `str` | `"default"` | Styling variant. One of `default`, `size`, `text`. |
 
 
 ## Messages
 
 This widget sends no messages.
 
-## See Also
+---
 
-* [Placeholder](../api/placeholder.md) code reference
+
+::: textual.widgets.Placeholder
+    options:
+      heading_level: 2

docs/widgets/radiobutton.md

@@ -56,9 +56,15 @@ The radio button widget provides the following component classes:
 
 ## Messages
 
-### ::: textual.widgets.RadioButton.Changed
+- [RadioButton.Changed][textual.widgets.RadioButton.Changed]
 
 ## See Also
 
-- [RadioButton](../api/radiobutton.md) code reference
 - [RadioSet](./radioset.md)
+
+---
+
+
+::: textual.widgets.RadioButton
+    options:
+      heading_level: 2

docs/widgets/radioset.md

@@ -31,7 +31,7 @@ The example below shows two radio sets, one built using a collection of
 
 ## Messages
 
-### ::: textual.widgets.RadioSet.Changed
+-  [RadioSet.Changed][textual.widgets.RadioSet.Changed]
 
 #### Example
 
@@ -56,5 +56,12 @@ Here is an example of using the message to react to changes in a `RadioSet`:
 
 ## See Also
 
-- [RadioSet](../api/radioset.md) code reference
+
 - [RadioButton](./radiobutton.md)
+
+---
+
+
+::: textual.widgets.RadioSet
+    options:
+      heading_level: 2

docs/widgets/static.md

@@ -31,5 +31,12 @@ This widget sends no messages.
 
 ## See Also
 
-* [Static](../api/static.md) code reference
 * [Label](./label.md)
+
+
+---
+
+
+::: textual.widgets.Static
+    options:
+      heading_level: 2

docs/widgets/switch.md

@@ -52,12 +52,15 @@ The switch widget provides the following component classes:
 
 ## Messages
 
-### ::: textual.widgets.Switch.Changed
+- [Switch.Changed][textual.widgets.Switch.Changed]
 
 ## Additional Notes
 
 - To remove the spacing around a `Switch`, set `border: none;` and `padding: 0;`.
 
-## See Also
+---
 
-- [Switch](../api/switch.md) code reference
+
+::: textual.widgets.Switch
+    options:
+      heading_level: 2

docs/widgets/tabbed_content.md

@@ -103,6 +103,22 @@ The following example contains a `TabbedContent` with three tabs.
 
 ## See also
 
-- [TabbedContent](../api/tabbed_content.md) code reference.
-- [Tabs](../api/tabs.md) code reference.
-- [ContentSwitcher](../api/content_switcher.md) code reference.
+
+- [Tabs](tabs.md)
+- [ContentSwitcher](content_switcher.md)
+
+
+---
+
+
+::: textual.widgets.TabbedContent
+    options:
+      heading_level: 2
+
+
+---
+
+
+::: textual.widgets.TabPane
+    options:
+      heading_level: 2

docs/widgets/tabs.md

@@ -61,8 +61,8 @@ The following example adds a `Tabs` widget above a text label. Press ++a++ to ad
 
 ## Messages
 
-### ::: textual.widgets.Tabs.TabActivated
-### ::: textual.widgets.Tabs.Cleared
+- [Tabs.TabActivate][textual.widgets.Tabs.TabActivated]
+- [Tabs.Cleared][textual.widgets.Tabs.Cleared]
 
 ## Bindings
 
@@ -73,6 +73,17 @@ The Tabs widget defines the following bindings:
       show_root_heading: false
       show_root_toc_entry: false
 
-## See Also
 
-- [Tabs](../api/tabs.md) code reference
+---
+
+
+::: textual.widgets.Tabs
+    options:
+      heading_level: 2
+
+
+---
+
+::: textual.widgets.Tab
+    options:
+      heading_level: 2

docs/widgets/text_log.md

@@ -39,6 +39,9 @@ The example below shows an application showing a `TextLog` with different kinds
 This widget sends no messages.
 
 
-## See Also
+---
 
-* [TextLog](../api/text_log.md) code reference
+
+::: textual.widgets.TextLog
+    options:
+      heading_level: 2

docs/widgets/tree.md

@@ -62,7 +62,16 @@ The tree widget provides the following component classes:
       show_root_heading: false
       show_root_toc_entry: false
 
-## See Also
 
-* [Tree][textual.widgets.Tree] code reference
-* [TreeNode][textual.widgets.tree.TreeNode] code reference
+---
+
+
+::: textual.widgets.Tree
+    options:
+      heading_level: 2
+
+---
+
+::: textual.widgets.tree.TreeNode
+    options:
+      heading_level: 2