Skip to content

Commit f4f75fa

Browse files
coordtcoordt
committed
Updated docs and styles
1 parent 4e524d8 commit f4f75fa

File tree

15 files changed

+579
-70
lines changed

15 files changed

+579
-70
lines changed

‎.github/workflows/docs-final.yml

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Deploy final documentation
2+
3+
on:
4+
push:
5+
branches: [ "master" ]
6+
7+
jobs:
8+
build:
9+
10+
runs-on: ubuntu-latest
11+
12+
steps:
13+
- name: Checkout
14+
uses: actions/checkout@v4
15+
with:
16+
fetch-depth: 0
17+
18+
- name: Set up Python 3.10
19+
uses: actions/setup-python@v5
20+
with:
21+
python-version: "3.10"
22+
23+
- name: Install dependencies
24+
run: |
25+
git pull --all
26+
python -m pip install ".[docs]"
27+
28+
- name: Build and deploy documentation
29+
run: |
30+
mkdocs gh-deploy --strict -v

‎.github/workflows/docs-preview.yml

+38
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy PR previews
2+
3+
on:
4+
pull_request:
5+
types:
6+
- opened
7+
- reopened
8+
- synchronize
9+
- closed
10+
11+
concurrency: preview-${{ github.ref }}
12+
13+
jobs:
14+
deploy-preview:
15+
runs-on: ubuntu-20.04
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
with:
20+
fetch-depth: 0
21+
22+
- name: Set up Python 3.10
23+
uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.10"
26+
27+
- name: Install dependencies
28+
run: |
29+
python -m pip install ".[docs]"
30+
31+
- name: Build documentation
32+
run: |
33+
mkdocs build --strict -v
34+
35+
- name: Deploy preview
36+
uses: rossjrw/pr-preview-action@v1
37+
with:
38+
source-dir: ./site/

‎docsrc/_static/css/custom.css

+9-67
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,12 @@
1-
.class .sig-prename.descclassname {
2-
display: none;
1+
/* Indentation. */
2+
div.doc-contents:not(.first) {
3+
padding-left: 25px;
4+
border-left: .05rem solid var(--md-typeset-table-color);
35
}
46

5-
.subheading {
6-
line-height: 1.25;
7-
margin-bottom: 0;
8-
color: #646776;
9-
}
10-
11-
.subheading + section > h1 {
12-
margin-top: 0;
13-
}
14-
15-
.field-list p {
16-
margin: 0;
17-
}
18-
19-
.field-list > dl {
20-
--gap: 1rem;
21-
--line-offset: calc(var(--gap) / 2);
22-
--line-thickness: 1px;
23-
--line-color: #e0e0e0;
24-
25-
display: grid;
26-
grid-template-columns: fit-content(30%) auto;
27-
grid-gap: var(--gap);
28-
margin-bottom: 1rem;
29-
overflow: hidden;
30-
}
31-
32-
.field-list > dl > dt {
33-
text-align: right;
34-
font-weight: bold;
35-
word-break: break-word;
36-
position: relative;
37-
}
38-
39-
[dir=ltr] .field-list > dl > dd {
40-
margin-top: 0;
41-
margin-left: 0;
42-
margin-bottom: 0;
43-
position: relative;
44-
}
45-
46-
/* Pseudo Element Shared Styling */
47-
.field-list > dl > dt::before,
48-
.field-list > dl > dt::after,
49-
.field-list > dl > dd::before,
50-
.field-list > dl > dd::after {
51-
content: '';
52-
position: absolute;
53-
background-color: var(--line-color);
54-
z-index: 1;
55-
}
56-
57-
/* Row Borders */
58-
.field-list > dl > dt::after,
59-
.field-list > dl > dd::after {
60-
inline-size: 100vw;
61-
block-size: var(--line-thickness);
62-
inset-inline-start: 0;
63-
inset-block-start: calc(var(--line-offset) * -1);
64-
}
65-
66-
67-
figure {
68-
padding-bottom: .75rem;
69-
padding-top: .5rem;
7+
/* Normal size fonts on parameter tables */
8+
.md-typeset div.doc-contents table {
9+
font-size: 1em;
10+
width: 100%;
11+
display: table;
7012
}

‎docsrc/_static/css/field-list.css

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
dl.field-list .doc-param-default, dl.doc-field-list .doc-param-default {
2+
float: none;
3+
}
4+
5+
dd.doc-field-def > p:last-child {
6+
padding-bottom: 0;
7+
margin-bottom: 0;
8+
}
9+
10+
dl.field-list, dl.doc-field-list {
11+
display: flex;
12+
flex-flow: row wrap;
13+
padding-left: 10px;
14+
}
15+
16+
dl.field-list > dt, dl.doc-field-list > dt {
17+
flex-basis: 20%;
18+
font-weight: bold;
19+
word-break: break-word;
20+
padding: 10px 0;
21+
border-bottom: 1px solid #e5e5e5;
22+
}
23+
24+
dl.field-list > dt:after {
25+
content: ":";
26+
}
27+
28+
dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def {
29+
flex-basis: 70%;
30+
flex-grow: 1;
31+
margin: 0;
32+
padding: 10px 0 10px 10px;
33+
border-bottom: 1px solid #e5e5e5;
34+
}
35+
36+
dl {
37+
margin-bottom: 15px;
38+
}
39+
40+
dd > :first-child {
41+
margin-top: 0;
42+
}
43+
44+
dd ul, dd table {
45+
margin-bottom: 10px;
46+
}
47+
48+
dd {
49+
margin-top: 3px;
50+
margin-bottom: 10px;
51+
margin-left: 30px;
52+
}
53+
54+
dl > dd:last-child,
55+
dl > dd:last-child > :last-child {
56+
margin-bottom: 0;
57+
}
58+
59+
dt:target, span.highlighted {
60+
background-color: #fbe54e;
61+
}

‎docsrc/_static/css/mkdocstrings.css

+12
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,15 @@ a.external:hover::after,
2525
a.autorefs-external:hover::after {
2626
background-color: var(--md-accent-fg-color);
2727
}
28+
29+
.doc-param-key, .doc-field-term, .doc-section-head {
30+
font-weight: bold;
31+
}
32+
33+
.doc.doc-heading {
34+
text-transform: none;
35+
}
36+
37+
h5.doc-heading, h6.doc-heading {
38+
font-size: 1em;
39+
}

‎docsrc/changelog.md

+4
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1+
---
2+
comments: true
3+
---
4+
15
{% include-markdown "../CHANGELOG.md" %}

‎docsrc/contributing.md

+4
Original file line numberDiff line numberDiff line change
@@ -1 +1,5 @@
1+
---
2+
comments: true
3+
---
4+
15
{% include-markdown "../CONTRIBUTING.md" rewrite-relative-urls=false %}

‎docsrc/index.md

+5
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
comments: true
3+
title: Bump My Version
4+
---
5+
16
# Bump My Version
27

38
{%

‎mkdocs.yml

+10-3
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ theme:
2323
palette:
2424
- media: "(prefers-color-scheme: light)"
2525
scheme: default
26+
primary: blue grey
2627
toggle:
2728
icon: material/toggle-switch-off-outline
2829
name: Switch to dark mode
@@ -31,13 +32,13 @@ theme:
3132
toggle:
3233
icon: material/toggle-switch
3334
name: Switch to light mode
34-
use_directory_urls: false
35+
use_directory_urls: true
3536
markdown_extensions:
3637
- abbr
3738
- admonition
3839
- attr_list
39-
- def_list
4040
- customblocks
41+
- def_list
4142
- footnotes
4243
- md_in_html
4344
- mdx_truly_sane_lists
@@ -48,12 +49,17 @@ markdown_extensions:
4849
emoji_generator: !!python/name:material.extensions.emoji.to_svg
4950
- pymdownx.highlight
5051
- pymdownx.snippets
51-
- pymdownx.superfences
52+
- pymdownx.superfences:
53+
custom_fences:
54+
- name: mermaid
55+
class: mermaid
56+
format: !!python/name:pymdownx.superfences.fence_div_format
5257
- pymdownx.tabbed:
5358
alternate_style: true
5459
slugify: !!python/object/apply:pymdownx.slugs.slugify
5560
kwds:
5661
case: lower
62+
- smarty
5763
- toc:
5864
permalink: true
5965
toc_depth: 3
@@ -105,6 +111,7 @@ extra_css:
105111
- _static/css/custom.css
106112
- _static/css/mkdocstrings.css
107113
- _static/css/cards.css
114+
- _static/css/field-list.css
108115

109116
#nav:
110117
# - General: "general/"

‎overrides/mkdocstrings/python/material/docstring/attributes.html

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
{{ log.debug("Rendering attributes section") }}
2+
3+
{% import "language.html" as lang with context %}
4+
5+
{% if config.docstring_section_style == "table" %}
6+
{% block table_style scoped %}
7+
<p><strong>{{ section.title or lang.t("Attributes:") }}</strong></p>
8+
<table>
9+
<thead>
10+
<tr>
11+
<th>{{ lang.t("Name") }}</th>
12+
<th>{{ lang.t("Type") }}</th>
13+
<th>{{ lang.t("Description") }}</th>
14+
</tr>
15+
</thead>
16+
<tbody>
17+
{% for attribute in section.value %}
18+
<tr>
19+
<td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></td>
20+
<td>
21+
{% if attribute.annotation %}
22+
{% with expression = attribute.annotation %}
23+
<code>{% include "expression.html" with context %}</code>
24+
{% endwith %}
25+
{% endif %}
26+
</td>
27+
<td>
28+
<div class="doc-md-description">
29+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
30+
</div>
31+
</td>
32+
</tr>
33+
{% endfor %}
34+
</tbody>
35+
</table>
36+
{% endblock table_style %}
37+
{% elif config.docstring_section_style == "list" %}
38+
{% block list_style scoped %}
39+
<p>{{ section.title or lang.t("Attributes:") }}</p>
40+
<ul>
41+
{% for attribute in section.value %}
42+
<li class="field-body">
43+
<b><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></b>
44+
{% if attribute.annotation %}
45+
{% with expression = attribute.annotation %}
46+
(<code>{% include "expression.html" with context %}</code>)
47+
{% endwith %}
48+
{% endif %}
49+
–
50+
<div class="doc-md-description">
51+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
52+
</div>
53+
</li>
54+
{% endfor %}
55+
</ul>
56+
{% endblock list_style %}
57+
{% elif config.docstring_section_style == "spacy" %}
58+
{% block spacy_style scoped %}
59+
<table>
60+
<thead>
61+
<tr>
62+
<th><b>{{ (section.title or lang.t("ATTRIBUTE")).rstrip(":").upper() }}</b></th>
63+
<th><b>{{ lang.t("DESCRIPTION") }}</b></th>
64+
</tr>
65+
</thead>
66+
<tbody>
67+
{% for attribute in section.value %}
68+
<tr>
69+
<td><code><span data-autorefs-optional-hover="{{ obj.path }}.{{ attribute.name }}">{{ attribute.name }}</span></code></td>
70+
<td class="doc-attribute-details">
71+
<div class="doc-md-description">
72+
{{ attribute.description|convert_markdown(heading_level, html_id) }}
73+
</div>
74+
<p>
75+
{% if attribute.annotation %}
76+
<span class="doc-attribute-annotation">
77+
<b>TYPE:</b>
78+
{% with expression = attribute.annotation %}
79+
<code>{% include "expression.html" with context %}</code>
80+
{% endwith %}
81+
</span>
82+
{% endif %}
83+
</p>
84+
</td>
85+
</tr>
86+
{% endfor %}
87+
</tbody>
88+
</table>
89+
{% endblock spacy_style %}
90+
{% endif %}

0 commit comments

Comments
 (0)