diff --git a/docs/_templates/python/material/_base/class.html b/docs/_templates/python/material/_base/class.html deleted file mode 100644 index 120fe338f1..0000000000 --- a/docs/_templates/python/material/_base/class.html +++ /dev/null @@ -1,114 +0,0 @@ -{{ log.debug("Rendering " + class.path) }} - -
-{% with html_id = class.path %} - - {% if root %} - {% set show_full_path = config.show_root_full_path %} - {% set root_members = True %} - {% elif root_members %} - {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} - {% set root_members = False %} - {% else %} - {% set show_full_path = config.show_object_full_path %} - {% endif %} - - - - {% if 1 %} - - {% filter heading(heading_level, - role="class", - id=html_id, - class="doc doc-heading", - toc_label=class.name) %} - - {% if config.separate_signature %} - {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} - {% elif config.merge_init_into_class and "__init__" in class.members -%} - {%- with function = class.members["__init__"] -%} - {%- filter highlight(language="python", inline=True) -%} - {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} - {%- include "signature.html" with context -%} - {%- endfilter -%} - {%- endwith -%} - {% else %} - {% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %} - {% endif %} - - {% with labels = ['class'] %} - {% include "labels.html" with context %} - {% endwith %} - - {% endfilter %} - - {% 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) -%} - def {% filter format_signature(config.line_length) %} -__init__{% include "signature.html" with context %} - {% endfilter %}: - {% endfilter %} - {% endwith %} - {% endif %} - {% endif %} - - {% else %} - {% if config.show_root_toc_entry %} - {% filter heading(heading_level, - role="class", - id=html_id, - toc_label=class.path if config.show_root_full_path else class.name, - hidden=True) %} - {% endfilter %} - {% endif %} - {% set heading_level = heading_level - 1 %} - {% endif %} - -
- {% if config.show_bases and class.bases %} -

- Bases: {% for expression in class.bases -%} - {% include "expression.html" with context %}{% if not loop.last %}, {% endif %} - {% endfor -%} -

- {% endif %} - - {% with docstring_sections = class.docstring.parsed %} - {% include "docstring.html" with context %} - {% endwith %} - - {% if config.merge_init_into_class %} - {% if "__init__" in class.members and class.members["__init__"].has_docstring %} - {% with docstring_sections = class.members["__init__"].docstring.parsed %} - {% include "docstring.html" with context %} - {% endwith %} - {% endif %} - {% endif %} - - {% if config.show_source %} - {% if config.merge_init_into_class %} - {% if "__init__" in class.members and class.members["__init__"].source %} -
- Source code in {{ class.relative_filepath }} - {{ class.members["__init__"].source|highlight(language="python", linestart=class.members["__init__"].lineno, linenums=True) }} -
- {% endif %} - {% elif class.source %} -
- Source code in {{ class.relative_filepath }} - {{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }} -
- {% endif %} - {% endif %} - - {% with obj = class %} - {% set root = False %} - {% set heading_level = heading_level + 1 %} - {% include "children.html" with context %} - {% endwith %} -
- -{% endwith %} -
diff --git a/docs/_templates/python/material/_base/docstring/admonition.html b/docs/_templates/python/material/_base/docstring/admonition.html deleted file mode 100644 index 2105eab710..0000000000 --- a/docs/_templates/python/material/_base/docstring/admonition.html +++ /dev/null @@ -1,5 +0,0 @@ -{{ log.debug("Rendering admonition") }} -
- {{ section.title|convert_markdown(heading_level, html_id, strip_paragraph=True) }} - {{ section.value.contents|convert_markdown(heading_level, html_id) }} -
diff --git a/docs/_templates/python/material/_base/docstring/attributes.html b/docs/_templates/python/material/_base/docstring/attributes.html deleted file mode 100644 index 99465b874b..0000000000 --- a/docs/_templates/python/material/_base/docstring/attributes.html +++ /dev/null @@ -1,78 +0,0 @@ -{{ log.debug("Rendering attributes section") }} -{% if config.docstring_section_style == "table" %} - {% block table_style %} -
{{ section.title or "Attributes" }}
- - - - - - - - - - {% for attribute in section.value %} - - - - - - {% endfor %} - -
NameTypeDescription
{{ attribute.name }} - {% if attribute.annotation %} - {% with expression = attribute.annotation %} - {% include "expression.html" with context %} - {% endwith %} - {% endif %} - {{ attribute.description|convert_markdown(heading_level, html_id) }}
- {% endblock table_style %} -{% elif config.docstring_section_style == "list" %} - {% block list_style %} -

{{ section.title or "Attributes:" }}

- - {% endblock list_style %} -{% elif config.docstring_section_style == "spacy" %} - {% block spacy_style %} - - - - - - - - - {% for attribute in section.value %} - - - - - {% endfor %} - -
{{ (section.title or "ATTRIBUTE").rstrip(":").upper() }}DESCRIPTION
{{ attribute.name }} - {{ attribute.description|convert_markdown(heading_level, html_id) }} -

- {% if attribute.annotation %} - - TYPE: - {% with expression = attribute.annotation %} - {% include "expression.html" with context %} - {% endwith %} - - {% endif %} -

-
- {% endblock spacy_style %} -{% endif %} diff --git a/docs/_templates/python/material/_base/docstring/parameters.html b/docs/_templates/python/material/_base/docstring/parameters.html deleted file mode 100644 index 10176a23ae..0000000000 --- a/docs/_templates/python/material/_base/docstring/parameters.html +++ /dev/null @@ -1,96 +0,0 @@ -{{ log.debug("Rendering parameters section") }} -{% if config.docstring_section_style == "table" %} - {% block table_style %} -
{{ section.title or "Parameters" }}
- - - - - - - - - - {% for parameter in section.value %} - - - - - - {% endfor %} - -
ParameterDefaultDescription
- {{ parameter.name }} -
- {% if parameter.annotation %} - {% with expression = parameter.annotation %} - {% include "expression.html" with context %} - {% endwith %} - {% endif %} - 		- {% if parameter.default %} - {% with expression = parameter.default %} - {% include "expression.html" with context %} - {% endwith %} - {% else %} - required - {% endif %} - {{ parameter.description|convert_markdown(heading_level, html_id) }}
- {% endblock table_style %} -{% elif config.docstring_section_style == "list" %} - {% block list_style %} -

{{ section.title or "Parameters:" }}

- - {% endblock list_style %} -{% elif config.docstring_section_style == "spacy" %} - {% block spacy_style %} - - - - - - - - - {% for parameter in section.value %} - - - - - {% endfor %} - -
{{ (section.title or "PARAMETER").rstrip(":").upper() }}DESCRIPTION
{{ parameter.name }} - {{ parameter.description|convert_markdown(heading_level, html_id) }} -

- {% if parameter.annotation %} - - TYPE: - {% with expression = parameter.annotation %} - {% include "expression.html" with context %} - {% endwith %} - - {% endif %} - {% if parameter.default %} - - DEFAULT: - {% with expression = parameter.default %} - {% include "expression.html" with context %} - {% endwith %} - - {% endif %} -

-
- {% endblock spacy_style %} -{% endif %} diff --git a/docs/_templates/python/material/_base/docstring/raises.html b/docs/_templates/python/material/_base/docstring/raises.html deleted file mode 100644 index 6e59775f46..0000000000 --- a/docs/_templates/python/material/_base/docstring/raises.html +++ /dev/null @@ -1,72 +0,0 @@ -{{ log.debug("Rendering raises section") }} -{% if config.docstring_section_style == "table" %} - {% block table_style %} -
{{ section.title or "Raises" }}
- - - - - - - - - {% for raises in section.value %} - - - - - {% endfor %} - -
TypeDescription
- {% if raises.annotation %} - {% with expression = raises.annotation %} - {% include "expression.html" with context %} - {% endwith %} - {% endif %} - {{ raises.description|convert_markdown(heading_level, html_id) }}
- {% endblock table_style %} -{% elif config.docstring_section_style == "list" %} - {% block list_style %} -

{{ section.title or "Raises:" }}

- - {% endblock list_style %} -{% elif config.docstring_section_style == "spacy" %} - {% block spacy_style %} - - - - - - - - - {% for raises in section.value %} - - - - - {% endfor %} - -
{{ (section.title or "RAISES").rstrip(":").upper() }}DESCRIPTION
- - {% with expression = raises.annotation %} - {% include "expression.html" with context %} - {% endwith %} - - - {{ raises.description|convert_markdown(heading_level, html_id) }} -
- {% endblock spacy_style %} -{% endif %} diff --git a/docs/_templates/python/material/_base/docstring/returns.html b/docs/_templates/python/material/_base/docstring/returns.html deleted file mode 100644 index a1f78b32c0..0000000000 --- a/docs/_templates/python/material/_base/docstring/returns.html +++ /dev/null @@ -1,91 +0,0 @@ -{{ log.debug("Rendering returns section") }} -{% if config.docstring_section_style == "table" %} - {% block table_style %} - {% set name_column = section.value|selectattr("name")|any %} -
{{ section.title or "Returns" }}
- - - - {% if name_column %}{% endif %} - - - - - - {% for returns in section.value %} - - {% if name_column %}{% endif %} - - - - {% endfor %} - -
NameTypeDescription
{% if returns.name %}{{ returns.name }}{% endif %} - {% if returns.annotation %} - {% with expression = returns.annotation %} - {% include "expression.html" with context %} - {% endwith %} - {% endif %} - {{ returns.description|convert_markdown(heading_level, html_id) }}
- {% endblock table_style %} -{% elif config.docstring_section_style == "list" %} - {% block list_style %} -

{{ section.title or "Returns:" }}

- - {% endblock list_style %} -{% elif config.docstring_section_style == "spacy" %} - {% block spacy_style %} - - - - - - - - - {% for returns in section.value %} - - - - - {% endfor %} - -
{{ (section.title or "RETURNS").rstrip(":").upper() }}DESCRIPTION
- {% if returns.name %} - {{ returns.name }} - {% elif returns.annotation %} - - {% with expression = returns.annotation %} - {% include "expression.html" with context %} - {% endwith %} - - {% endif %} - - {{ returns.description|convert_markdown(heading_level, html_id) }} - {% if returns.name and returns.annotation %} -

- - TYPE: - {% with expression = returns.annotation %} - {% include "expression.html" with context %} - {% endwith %} - -

- {% endif %} -
- {% endblock spacy_style %} -{% endif %} diff --git a/docs/_templates/python/material/_base/function.html b/docs/_templates/python/material/_base/function.html deleted file mode 100644 index 58a4c37ad4..0000000000 --- a/docs/_templates/python/material/_base/function.html +++ /dev/null @@ -1,73 +0,0 @@ -{{ log.debug("Rendering " + function.path) }} - -
-{% with html_id = function.path %} - - {% if root %} - {% set show_full_path = config.show_root_full_path %} - {% set root_members = True %} - {% elif root_members %} - {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %} - {% set root_members = False %} - {% else %} - {% set show_full_path = config.show_object_full_path %} - {% endif %} - - {% if not root or config.show_root_heading %} - - {% filter heading(heading_level, - role="function", - id=html_id, - class="doc doc-heading", - toc_label=function.name ~ "()") %} - - {% if config.separate_signature %} - {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %} - {% else %} - {% filter highlight(language="python", inline=True) %} - {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %} - {% include "signature.html" with context %} - {% endfilter %} - {% endif %} - {% 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 %} - - {% endfilter %} - - {% if config.separate_signature %} - {% filter highlight(language="python", inline=False) %} -def {% filter format_signature(config.line_length) %} - {% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %} - {% include "signature.html" with context %} - {% endfilter %}: - {% endfilter %} - {% endif %} - - {% else %} - {% if config.show_root_toc_entry %} - {% filter heading(heading_level, - role="function", - id=html_id, - toc_label=function.path if config.show_root_full_path else function.name, - hidden=True) %} - {% endfilter %} - {% endif %} - {% set heading_level = heading_level - 1 %} - {% endif %} - -
- {% with docstring_sections = function.docstring.parsed %} - {% include "docstring.html" with context %} - {% endwith %} - - {% if config.show_source and function.source %} -
- Source code in {{ function.relative_filepath }} - {{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }} -
- {% endif %} -
- -{% endwith %} -
diff --git a/docs/_templates/python/material/_base/signature.html b/docs/_templates/python/material/_base/signature.html deleted file mode 100644 index 2e1ecd6357..0000000000 --- a/docs/_templates/python/material/_base/signature.html +++ /dev/null @@ -1,48 +0,0 @@ -{%- if config.show_signature -%} - {{ log.debug("Rendering signature") }} - {%- with -%} - - {%- set ns = namespace(has_pos_only=False, render_pos_only_separator=True, render_kw_only_separator=True, equal="=") -%} - - {%- if config.show_signature_annotations -%} - {%- set ns.equal = " = " -%} - {%- endif -%} - - ( - {%- for parameter in function.parameters -%} - {%- 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 ns.render_kw_only_separator -%} - {%- set ns.render_kw_only_separator = False %}*, {% endif -%} - {%- endif -%} - {%- endif -%} - - {%- if config.show_signature_annotations and parameter.annotation is not none -%} - {%- set annotation = ": " + parameter.annotation|safe -%} - {%- endif -%} - - {%- if parameter.default is not none and parameter.kind.value != "variadic positional" and parameter.kind.value != "variadic keyword" -%} - {%- set default = ns.equal + parameter.default|safe -%} - {%- endif -%} - - {%- if parameter.kind.value == "variadic positional" -%} - {%- set ns.render_kw_only_separator = False -%} - {%- endif -%} - - {% if parameter.kind.value == "variadic positional" %}*{% elif parameter.kind.value == "variadic keyword" %}**{% endif -%} - {{ parameter.name }}{{ annotation }}{{ default }} - {%- if not loop.last %}, {% endif -%} - - {%- endif -%} - {%- endfor -%} - ) - {%- if config.show_signature_annotations and function.annotation %} -> {{ function.annotation|safe }}{%- endif -%} - - {%- endwith -%} -{%- endif -%} diff --git a/docs/api/await_complete.md b/docs/api/await_complete.md index cefcedd959..1782553bb4 100644 --- a/docs/api/await_complete.md +++ b/docs/api/await_complete.md @@ -3,8 +3,8 @@ title: "textual.await_complete" --- This object is returned by methods that do work in the *background*. -You can await the return value if you need to know when that work has completed. -If you ignore it, Textual will wait for the work to be done before handling the next message. +You can await this object if you need to know when that work has completed. +Or you can ignore it, and Textual will automatically await the work before handling the next message. !!! note diff --git a/docs/api/await_remove.md b/docs/api/await_remove.md index 64e8a4ab5f..d13479a3f5 100644 --- a/docs/api/await_remove.md +++ b/docs/api/await_remove.md @@ -3,9 +3,9 @@ title: "textual.await_remove" --- -This object is returned by [`Widget.remove()`][textual.widget.Widget.remove], and other methods which remove widgets. -You can await the return value if you need to know exactly when the widgets have been removed. -If you ignore it, Textual will wait for the widgets to be removed before handling the next message. +This object is returned by [`Widget.remove()`][textual.widget.Widget.remove] and other methods which remove widgets. +You can await the return value if you need to know exactly when the widget(s) have been removed. +Or you can ignore it and Textual will wait for the widgets to be removed before handling the next message. !!! note diff --git a/mkdocs-common.yml b/mkdocs-common.yml index 883653f6a1..6bae8ebdbb 100644 --- a/mkdocs-common.yml +++ b/mkdocs-common.yml @@ -71,10 +71,12 @@ plugins: handlers: python: options: + modernize_annotations: false show_symbol_type_heading: true show_symbol_type_toc: true show_signature_annotations: false separate_signature: true + signature_crossrefs: true merge_init_into_class: true docstring_options: ignore_init_summary: true diff --git a/src/textual/binding.py b/src/textual/binding.py index 3cc2828df3..5ff189bb15 100644 --- a/src/textual/binding.py +++ b/src/textual/binding.py @@ -53,7 +53,7 @@ class Binding: class ActiveBinding(NamedTuple): - """Information about an active binding (returned from [active_bindings][textual.screen.active_bindings]).""" + """Information about an active binding (returned from [active_bindings][textual.screen.Screen.active_bindings]).""" node: DOMNode """The node where the binding is defined.""" diff --git a/src/textual/cache.py b/src/textual/cache.py index 9186df7cda..85937b3449 100644 --- a/src/textual/cache.py +++ b/src/textual/cache.py @@ -1,8 +1,8 @@ """ -Containers to implement caching. +Cache classes are dict-like containers used to avoid recalculating expensive operations such as rendering. -These are used in Textual to avoid recalculating expensive operations, such as rendering. +You can also use them in your own apps if you need them. """ diff --git a/src/textual/constants.py b/src/textual/constants.py index 6d0ebfe323..9c420a7dc7 100644 --- a/src/textual/constants.py +++ b/src/textual/constants.py @@ -1,5 +1,5 @@ """ -Constants that we might want to expose via the public API. +This module contains constants, which may be set in environment variables. """ from __future__ import annotations