Skip to content

Commit d97c52a

Browse files
statmlbenstatmlben
committed
update doc
1 parent 66e495e commit d97c52a

File tree

13 files changed

+720
-52
lines changed

13 files changed

+720
-52
lines changed

‎doc/_templates/autoapi/index.rst‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎doc/source/_static/css/label.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.summarylabel {
2+
background-color: var(--color-foreground-secondary);
3+
color: var(--color-background-secondary);
4+
font-size: 70%;
5+
padding-left: 2px;
6+
padding-right: 2px;
7+
border-radius: 3px;
8+
vertical-align: 15%;
9+
padding-bottom: 2px;
10+
filter: opacity(40%);
11+
}
12+
13+
14+
table.summarytable {
15+
width: 100%;
16+
}

‎doc/source/_templates/autoapi/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
API Reference
2+
=============
3+
4+
This page contains auto-generated API reference documentation.
5+
6+
.. toctree::
7+
:titlesonly:
8+
9+
{% for page in pages %}
10+
{{ page.include_path }}
11+
{% endfor %}
12+

‎doc/source/_templates/autoapi/macros.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{# AutoApiSummary replacement macro #}
2+
{#
3+
The intent of this macro is to replace the autoapisummary directive with the following
4+
improvements:
5+
1) Method signature is generated without typing annotation regardless of the value of
6+
`autodoc_typehints`
7+
2) Properties are treated like attribute (but labelled as properties).
8+
3) Label are added as summary prefix to indicate if the member is a property, class
9+
method, or static method.
10+
11+
Copyright: Antoine Beyeler, 2022
12+
License: MIT
13+
#}
14+
15+
{# Renders an object's name with a proper reference and optional signature.
16+
17+
The signature is re-generated from obj.obj.args, which is undocumented but is the
18+
only way to have a type-less signature if `autodoc_typehints` is `signature` or
19+
`both`. #}
20+
{% macro _render_item_name(obj, sig=False) -%}
21+
:py:obj:`{{ obj.name }} <{{ obj.id }}>`
22+
{%- if sig -%}
23+
\ (
24+
{%- for arg in obj.obj.args -%}
25+
{%- if arg[0] %}{{ arg[0]|replace('*', '\*') }}{% endif -%}{{ arg[1] -}}
26+
{%- if not loop.last %}, {% endif -%}
27+
{%- endfor -%}
28+
){%- endif -%}
29+
{%- endmacro %}
30+
31+
32+
{# Generates a single object optionally with a signature and a labe. #}
33+
{% macro _item(obj, sig=False, label='') %}
34+
* - {{ _render_item_name(obj, sig) }}
35+
- {% if label %}:summarylabel:`{{ label }}` {% endif %}{% if obj.summary %}{{ obj.summary }}{% else %}\-{% endif +%}
36+
{% endmacro %}
37+
38+
39+
40+
{# Generate an autosummary-like table with the provided members. #}
41+
{% macro auto_summary(objs, title='') -%}
42+
43+
.. list-table:: {{ title }}
44+
:header-rows: 0
45+
:widths: auto
46+
:class: summarytable {#- apply CSS class to customize styling +#}
47+
48+
{% for obj in objs -%}
49+
{#- should the full signature be used? -#}
50+
{%- set sig = (obj.type in ['method', 'function'] and not 'property' in obj.properties) -%}
51+
52+
{#- compute label -#}
53+
{%- if 'property' in obj.properties -%}
54+
{%- set label = 'prop' -%}
55+
{%- elif 'classmethod' in obj.properties -%}
56+
{%- set label = 'class' -%}
57+
{%- elif 'abstractmethod' in obj.properties -%}
58+
{%- set label = 'abc' -%}
59+
{%- elif 'staticmethod' in obj.properties -%}
60+
{%- set label = 'static' -%}
61+
{%- else -%}
62+
{%- set label = '' -%}
63+
{%- endif -%}
64+
65+
{{- _item(obj, sig=sig, label=label) -}}
66+
{%- endfor -%}
67+
68+
{% endmacro %}

‎doc/source/_templates/autoapi/python/class.rst‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
{% import 'macros.rst' as macros %}
2+
3+
{% if obj.display %}
4+
.. py:{{ obj.type }}:: {{ obj.short_name }}{% if obj.args %}({{ obj.args }}){% endif %}
5+
{% for (args, return_annotation) in obj.overloads %}
6+
{{ " " * (obj.type | length) }} {{ obj.short_name }}{% if args %}({{ args }}){% endif %}
7+
{% endfor %}
8+
9+
10+
{% if obj.bases %}
11+
{% if "show-inheritance" in autoapi_options %}
12+
Bases: {% for base in obj.bases %}{{ base|link_objs }}{% if not loop.last %}, {% endif %}{% endfor %}
13+
{% endif %}
14+
15+
16+
{% if "show-inheritance-diagram" in autoapi_options and obj.bases != ["object"] %}
17+
.. autoapi-inheritance-diagram:: {{ obj.obj["full_name"] }}
18+
:parts: 1
19+
{% if "private-members" in autoapi_options %}
20+
:private-bases:
21+
{% endif %}
22+
23+
{% endif %}
24+
{% endif %}
25+
{% if obj.docstring %}
26+
{{ obj.docstring|indent(3) }}
27+
{% endif %}
28+
{% if "inherited-members" in autoapi_options %}
29+
{% set visible_classes = obj.classes|selectattr("display")|list %}
30+
{% else %}
31+
{% set visible_classes = obj.classes|rejectattr("inherited")|selectattr("display")|list %}
32+
{% endif %}
33+
{% for klass in visible_classes %}
34+
{{ klass.render()|indent(3) }}
35+
{% endfor %}
36+
{% if "inherited-members" in autoapi_options %}
37+
{% set visible_attributes = obj.attributes|selectattr("display")|list %}
38+
{% else %}
39+
{% set visible_attributes = obj.attributes|rejectattr("inherited")|selectattr("display")|list %}
40+
{% endif %}
41+
{% if "inherited-members" in autoapi_options %}
42+
{% set visible_methods = obj.methods|selectattr("display")|list %}
43+
{% else %}
44+
{% set visible_methods = obj.methods|rejectattr("inherited")|selectattr("display")|list %}
45+
{% endif %}
46+
47+
{% if visible_methods or visible_attributes %}
48+
Overview
49+
========
50+
51+
{% set summary_methods = visible_methods|rejectattr("properties", "contains", "property")|list %}
52+
{% set summary_attributes = visible_attributes + visible_methods|selectattr("properties", "contains", "property")|list %}
53+
{% if summary_attributes %}
54+
{{ macros.auto_summary(summary_attributes, title="Attributes")|indent(3) }}
55+
{% endif %}
56+
57+
{% if summary_methods %}
58+
{{ macros.auto_summary(summary_methods, title="Methods")|indent(3) }}
59+
{% endif %}
60+
61+
Members
62+
=======
63+
64+
{% for attribute in visible_attributes %}
65+
{{ attribute.render()|indent(3) }}
66+
{% endfor %}
67+
{% for method in visible_methods %}
68+
{{ method.render()|indent(3) }}
69+
{% endfor %}
70+
{% endif %}
71+
{% endif %}

‎doc/source/_templates/autoapi/python/module.rst‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
{% import 'macros.rst' as macros %}
2+
3+
{% if not obj.display %}
4+
:orphan:
5+
6+
{% endif %}
7+
{{ obj.name }}
8+
{{ "=" * obj.name|length }}
9+
10+
.. py:module:: {{ obj.name }}
11+
12+
{% if obj.docstring %}
13+
.. autoapi-nested-parse::
14+
15+
{{ obj.docstring|indent(3) }}
16+
17+
{% endif %}
18+
19+
{% block subpackages %}
20+
{% set visible_subpackages = obj.subpackages|selectattr("display")|list %}
21+
{% if visible_subpackages %}
22+
Subpackages
23+
-----------
24+
.. toctree::
25+
:titlesonly:
26+
:maxdepth: 3
27+
28+
{% for subpackage in visible_subpackages %}
29+
{{ subpackage.short_name }}/index.rst
30+
{% endfor %}
31+
32+
33+
{% endif %}
34+
{% endblock %}
35+
{% block submodules %}
36+
{% set visible_submodules = obj.submodules|selectattr("display")|list %}
37+
{% if visible_submodules %}
38+
Submodules
39+
----------
40+
.. toctree::
41+
:titlesonly:
42+
:maxdepth: 1
43+
44+
{% for submodule in visible_submodules %}
45+
{{ submodule.short_name }}/index.rst
46+
{% endfor %}
47+
48+
49+
{% endif %}
50+
{% endblock %}
51+
{% block content %}
52+
{% if obj.all is not none %}
53+
{% set visible_children = obj.children|selectattr("display")|selectattr("short_name", "in", obj.all)|list %}
54+
{% elif obj.type is equalto("package") %}
55+
{% set visible_children = obj.children|selectattr("display")|list %}
56+
{% else %}
57+
{% set visible_children = obj.children|selectattr("display")|rejectattr("imported")|list %}
58+
{% endif %}
59+
{% if visible_children %}
60+
Overview
61+
--------
62+
63+
{% set visible_classes = visible_children|selectattr("type", "equalto", "class")|list %}
64+
{% set visible_functions = visible_children|selectattr("type", "equalto", "function")|list %}
65+
{% set visible_attributes = visible_children|selectattr("type", "equalto", "data")|list %}
66+
{% if "show-module-summary" in autoapi_options and (visible_classes or visible_functions) %}
67+
{% block classes scoped %}
68+
{% if visible_classes %}
69+
{{ macros.auto_summary(visible_classes, title="Classes") }}
70+
{% endif %}
71+
{% endblock %}
72+
73+
{% block functions scoped %}
74+
{% if visible_functions %}
75+
{{ macros.auto_summary(visible_functions, title="Function") }}
76+
{% endif %}
77+
{% endblock %}
78+
79+
{% block attributes scoped %}
80+
{% if visible_attributes %}
81+
{{ macros.auto_summary(visible_attributes, title="Attributes") }}
82+
{% endif %}
83+
{% endblock %}
84+
{% endif %}
85+
86+
{% if visible_classes %}
87+
Classes
88+
-------
89+
{% for obj_item in visible_classes %}
90+
{{ obj_item.render()|indent(0) }}
91+
{% endfor %}
92+
{% endif %}
93+
94+
{% if visible_functions %}
95+
Functions
96+
---------
97+
{% for obj_item in visible_functions %}
98+
{{ obj_item.render()|indent(0) }}
99+
{% endfor %}
100+
{% endif %}
101+
102+
{% if visible_attributes %}
103+
Attributes
104+
----------
105+
{% for obj_item in visible_attributes %}
106+
{{ obj_item.render()|indent(0) }}
107+
{% endfor %}
108+
{% endif %}
109+
110+
111+
{% endif %}
112+
{% endblock %}

‎doc/source/autoapi/index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
API Reference
2+
=============
3+
4+
This page contains auto-generated API reference documentation.
5+
6+
.. toctree::
7+
:titlesonly:
8+
9+
/autoapi/rehline/index

0 commit comments

Comments
 (0)