alihan/textual
1
0
Fork 0
mirror of https://github.com/Textualize/textual.git synced 2025-10-17 02:38:12 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs update (#2239)

Browse Source 
* docs update

* class template

* no annotations in sig
This commit is contained in:
Will McGugan
2023-04-07 18:57:56 +01:00
committed by GitHub
parent 79ebbff933
commit 6c958a1140
11 changed files with 612 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
docs/_templates/python/material/_base/class.html vendored Normal file
View File

@@ -0,0 +1,113 @@
{{ log.debug("Rendering " + class.path) }}
<div class="doc doc-object doc-class">
{% 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 not root or config.show_root_heading %}
{% filter heading(heading_level,
role="class",
id=html_id,
class="doc doc-heading",
toc_label=class.name) %}
{% if config.separate_signature %}
<span class="doc doc-object-name doc-class-name">{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</span>
{% 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 %}
<code>{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}</code>
{% endif %}
{% with labels = class.labels %}
{% 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) %}
class {% filter format_signature(config.line_length) %}
{% if show_full_path %}{{ class.path }}{% else %}{{ class.name }}{% endif %}
{% 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 %}
<div class="doc doc-contents {% if root %}first{% endif %}">
{% if config.show_bases and class.bases %}
<p class="doc doc-class-bases">
Bases: {% for expression in class.bases -%}
<code>{% include "expression.html" with context %}</code>{% if not loop.last %}, {% endif %}
{% endfor -%}
</p>
{% 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 %}
<details class="quote">
<summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
{{ class.members["__init__"].source|highlight(language="python", linestart=class.members["__init__"].lineno, linenums=True) }}
</details>
{% endif %}
{% elif class.source %}
<details class="quote">
<summary>Source code in <code>{{ class.relative_filepath }}</code></summary>
{{ class.source|highlight(language="python", linestart=class.lineno, linenums=True) }}
</details>
{% endif %}
{% endif %}
{% with obj = class %}
{% set root = False %}
{% set heading_level = heading_level + 1 %}
{% include "children.html" with context %}
{% endwith %}
</div>
{% endwith %}
</div>

78
docs/_templates/python/material/_base/docstring/attributes.html vendored Normal file
View File

@@ -0,0 +1,78 @@
{{ log.debug("Rendering attributes section") }}
{% if config.docstring_section_style == "table" %}
{% block table_style %}
<h5>{{ section.title or "Attributes" }}</h5>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{% for attribute in section.value %}
<tr>
<td><code>{{ attribute.name }}</code></td>
<td>
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% endif %}
</td>
<td>{{ attribute.description|convert_markdown(heading_level, html_id) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock table_style %}
{% elif config.docstring_section_style == "list" %}
{% block list_style %}
<p>{{ section.title or "Attributes:" }}</p>
<ul>
{% for attribute in section.value %}
<li class="field-body">
<b>{{ attribute.name }}</b>
{% if attribute.annotation %}
{% with expression = attribute.annotation %}
(<code>{% include "expression.html" with context %}</code>)
{% endwith %}
{% endif %}
– {{ attribute.description|convert_markdown(heading_level, html_id) }}
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% elif config.docstring_section_style == "spacy" %}
{% block spacy_style %}
<table>
<thead>
<tr>
<th><b>{{ (section.title or "ATTRIBUTE").rstrip(":").upper() }}</b></th>
<th><b>DESCRIPTION</b></th>
</tr>
</thead>
<tbody>
{% for attribute in section.value %}
<tr>
<td><code>{{ attribute.name }}</code></td>
<td class="doc-attribute-details">
{{ attribute.description|convert_markdown(heading_level, html_id) }}
<p>
{% if attribute.annotation %}
<span class="doc-attribute-annotation">
<b>TYPE:</b>
{% with expression = attribute.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
{% endif %}
</p>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock spacy_style %}
{% endif %}

96
docs/_templates/python/material/_base/docstring/parameters.html vendored Normal file
View File

@@ -0,0 +1,96 @@
{{ log.debug("Rendering parameters section") }}
{% if config.docstring_section_style == "table" %}
{% block table_style %}
<h5>{{ section.title or "Parameters" }}</h5>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
{% for parameter in section.value %}
<tr>
<td><code>{{ parameter.name }}</code></td>
<td>
{% if parameter.annotation %}
{% with expression = parameter.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% endif %}
</td>
<td>{{ parameter.description|convert_markdown(heading_level, html_id) }}</td>
<td>
{% if parameter.default %}
{% with expression = parameter.default %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% else %}
<em>required</em>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock table_style %}
{% elif config.docstring_section_style == "list" %}
{% block list_style %}
<p>{{ section.title or "Parameters:" }}</p>
<ul>
{% for parameter in section.value %}
<li class="field-body">
<b>{{ parameter.name }}</b>
{% if parameter.annotation %}
{% with expression = parameter.annotation %}
(<code>{% include "expression.html" with context %}</code>)
{% endwith %}
{% endif %}
– {{ parameter.description|convert_markdown(heading_level, html_id) }}
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% elif config.docstring_section_style == "spacy" %}
{% block spacy_style %}
<table>
<thead>
<tr>
<th><b>{{ (section.title or "PARAMETER").rstrip(":").upper() }}</b></th>
<th><b>DESCRIPTION</b></th>
</tr>
</thead>
<tbody>
{% for parameter in section.value %}
<tr>
<td><code>{{ parameter.name }}</code></td>
<td class="doc-param-details">
{{ parameter.description|convert_markdown(heading_level, html_id) }}
<p>
{% if parameter.annotation %}
<span class="doc-param-annotation">
<b>TYPE:</b>
{% with expression = parameter.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
{% endif %}
{% if parameter.default %}
<span class="doc-param-default">
<b>DEFAULT:</b>
{% with expression = parameter.default %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
{% endif %}
</p>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock spacy_style %}
{% endif %}

72
docs/_templates/python/material/_base/docstring/raises.html vendored Normal file
View File

@@ -0,0 +1,72 @@
{{ log.debug("Rendering raises section") }}
{% if config.docstring_section_style == "table" %}
{% block table_style %}
<h5>{{ section.title or "Raises" }}</h5>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{% for raises in section.value %}
<tr>
<td>
{% if raises.annotation %}
{% with expression = raises.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% endif %}
</td>
<td>{{ raises.description|convert_markdown(heading_level, html_id) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock table_style %}
{% elif config.docstring_section_style == "list" %}
{% block list_style %}
<p>{{ section.title or "Raises:" }}</p>
<ul>
{% for raises in section.value %}
<li class="field-body">
{% if raises.annotation %}
{% with expression = raises.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
–
{% endif %}
{{ raises.description|convert_markdown(heading_level, html_id) }}
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% elif config.docstring_section_style == "spacy" %}
{% block spacy_style %}
<table>
<thead>
<tr>
<th><b>{{ (section.title or "RAISES").rstrip(":").upper() }}</b></th>
<th><b>DESCRIPTION</b></th>
</tr>
</thead>
<tbody>
{% for raises in section.value %}
<tr>
<td>
<span class="doc-raises-annotation">
{% with expression = raises.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
</td>
<td class="doc-raises-details">
{{ raises.description|convert_markdown(heading_level, html_id) }}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock spacy_style %}
{% endif %}

91
docs/_templates/python/material/_base/docstring/returns.html vendored Normal file
View File

@@ -0,0 +1,91 @@
{{ log.debug("Rendering returns section") }}
{% if config.docstring_section_style == "table" %}
{% block table_style %}
{% set name_column = section.value|selectattr("name")|any %}
<h5>{{ section.title or "Returns" }}</h5>
<table>
<thead>
<tr>
{% if name_column %}<th>Name</th>{% endif %}
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
{% for returns in section.value %}
<tr>
{% if name_column %}<td>{% if returns.name %}<code>{{ returns.name }}</code>{% endif %}</td>{% endif %}
<td>
{% if returns.annotation %}
{% with expression = returns.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
{% endif %}
</td>
<td>{{ returns.description|convert_markdown(heading_level, html_id) }}</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock table_style %}
{% elif config.docstring_section_style == "list" %}
{% block list_style %}
<p>{{ section.title or "Returns:" }}</p>
<ul>
{% for returns in section.value %}
<li class="field-body">
{% if returns.name %}<b>{{ returns.name }}</b>{% endif %}
{% if returns.annotation %}
{% with expression = returns.annotation %}
{% if returns.name %}({% endif %}
<code>{% include "expression.html" with context %}</code>
{% if returns.name %}){% endif %}
{% endwith %}
{% endif %}
– {{ returns.description|convert_markdown(heading_level, html_id) }}
</li>
{% endfor %}
</ul>
{% endblock list_style %}
{% elif config.docstring_section_style == "spacy" %}
{% block spacy_style %}
<table>
<thead>
<tr>
<th><b>{{ (section.title or "RETURNS").rstrip(":").upper() }}</b></th>
<th><b>DESCRIPTION</b></th>
</tr>
</thead>
<tbody>
{% for returns in section.value %}
<tr>
<td>
{% if returns.name %}
<code>{{ returns.name }}</code>
{% elif returns.annotation %}
<span class="doc-returns-annotation">
{% with expression = returns.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
{% endif %}
</td>
<td class="doc-returns-details">
{{ returns.description|convert_markdown(heading_level, html_id) }}
{% if returns.name and returns.annotation %}
<p>
<span class="doc-returns-annotation">
<b>TYPE:</b>
{% with expression = returns.annotation %}
<code>{% include "expression.html" with context %}</code>
{% endwith %}
</span>
</p>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% endblock spacy_style %}
{% endif %}

74
docs/_templates/python/material/_base/function.html vendored Normal file
View File

@@ -0,0 +1,74 @@
{{ log.debug("Rendering " + function.path) }}
<div class="doc doc-object doc-function">
{% 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 %}
<span class="doc doc-object-name doc-function-name">{% if show_full_path %}{{ function.path }}{% else %}{{ function.name }}{% endif %}</span>
{% 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 %}
{% 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 %}
<div class="doc doc-contents {% if root %}first{% endif %}">
{% with docstring_sections = function.docstring.parsed %}
{% include "docstring.html" with context %}
{% endwith %}
{% if config.show_source and function.source %}
<details class="quote">
<summary>Source code in <code>{{ function.relative_filepath }}</code></summary>
{{ function.source|highlight(language="python", linestart=function.lineno, linenums=True) }}
</details>
{% endif %}
</div>
{% endwith %}
</div>

48
docs/_templates/python/material/_base/signature.html vendored Normal file
View File

@@ -0,0 +1,48 @@
{%- 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 parameter.name not in ("self", "cls") or loop.index0 > 0 or not (function.parent and function.parent.is_class) -%}
{%- 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 -%}

27
docs/stylesheets/custom.css
View File

@@ -13,7 +13,7 @@ h3 .doc-heading code {
monospace;
}
body[data-md-color-primary="black"] .excalidraw svg {
body[data-md-color-primary="black"] .excalidraw svg {
filter: invert(100%) hue-rotate(180deg);
}
@@ -42,3 +42,28 @@ body[data-md-color-primary="black"] .excalidraw svg rect {
height: 100%;
border: 0;
}
/* Indentation. */
div.doc-contents:not(.first) .doc-contents {
padding-left: 25px;
border-left: .05rem solid var(--md-typeset-table-color);
}
/* Avoid breaking parameters name, etc. in table cells. */
td code {
word-break: normal !important;
}
.doc-label code {
background: transparent;
opacity: 0.8;
float: right;
}
.doc-function p strong {
opacity: 0.85;
}

7
mkdocs-common.yml
View File

@@ -71,8 +71,11 @@ plugins:
- https://docs.python.org/3/objects.inv
- https://rich.readthedocs.io/en/stable/objects.inv
options:
show_root_heading: true
show_root_full_path: false
show_signature_annotations: false
separate_signature: true
merge_init_into_class: true
docstring_options:
ignore_init_summary: true
show_source: false
filters:
- "!^_"

9
src/textual/app.py
View File

@@ -1,3 +1,8 @@
"""
The base class for all Textual apps.
"""
from __future__ import annotations
import asyncio
@@ -268,14 +273,14 @@ class App(Generic[ReturnType], DOMNode):
CSS_PATH: CSSPathType | None = None
TITLE: str | None = None
"""str | None: The default title for the application.
"""The default title for the application.
If set to a string, this sets the default title for the application. See
also the `title` attribute.
"""
SUB_TITLE: str | None = None
"""str | None: The default sub-title for the application.
"""The default sub-title for the application.
If set to a string, this sets the default sub-title for the application. See
also the `sub_title` attribute.

2
src/textual/widgets/_list_view.py
View File

@@ -78,6 +78,8 @@ class ListView(VerticalScroll, can_focus=True, can_focus_children=False):
disabled: bool = False,
) -> None:
"""
Initialize a ListView.
Args:
*children: The ListItems to display in the list.
initial_index: The index that should be highlighted when the list is first mounted.