Skip to content

Commit ed03795

Browse files
FeodorFitsnerFeodorFitsner
authored
Customized mkdocs templates (#18)
* Add custom Jinja templates for mkdocstrings Introduces custom templates for Python material documentation in mkdocstrings and configures mkdocs.yml to use them. Includes templates for attribute, class, function, and summary, with logging and error triggers for debugging and override verification. * Remove "python" templates * Create placeholder.txt * Original mkdocs templates * Customized templates * Updated mkdocs settings and extra css * Improve chart docs and PlotlyChart docstring formatting Enhanced documentation for line_chart, pie_chart, and plotly_chart with better formatting, options, and example presentation. Refined the PlotlyChart class docstring for clarity and improved reference to the figure attribute. * Update doc symbol styles and TOC entry settings Added new icon imports and styles for class symbols in mkdocstrings.css. Adjusted show_root_toc_entry settings in mkdocs.yml and line_chart.md for improved documentation navigation. * Update docs and styles for platform support and branding Revised platform support tables in README and docs to a more compact format. Updated mkdocs site name to 'Flet Charts' and changed theme colors to pink and light blue. Improved mkdocstrings.css for better icon styling and color scheme support. * Update logo.svg with new design and dimensions Replaces the previous logo.svg with a redesigned version featuring a circular white background, updated paths, and new dimensions (170x170). The new SVG is simplified and modernized for improved appearance and scalability. * Better logo * Update Material Symbols font settings in CSS Adjusted the @import URL and font-variation-settings for Material Symbols in mkdocstrings.css to use GRAD 200 instead of 0, ensuring consistent icon appearance. * Enable summary by default for all classes * Update logo.svg * Refactor chart controls to use LayoutControl Changed BarChart, LineChart, PieChart, and ScatterChart to inherit from ft.LayoutControl instead of ft.ConstrainedControl for improved layout handling. Updated documentation to enhance API reference structure, add diagrams, and improve class docstring visibility. Removed poetry install instructions from README and docs. * Remove docs workflow and update documentation link Deleted the GitHub Actions workflow for documentation deployment and updated the README to point to the new documentation URL. * Add GitHub repo icon to MkDocs theme Configured the MkDocs theme to use the FontAwesome GitHub brand icon for the repo. This enhances the visual representation of the repository link in the documentation. * Update copyright and theme settings in mkdocs.yml Changed copyright to Appveyor Systems Inc. and removed edit_uri. Also removed 'edit' and 'view' actions from theme features for documentation. * Refactor chart docs to use macros for class rendering Replaced repetitive class documentation blocks in chart and type markdown files with Jinja macros for consistency and maintainability. Added docs/extras/macros/__init__.py to define macros for rendering class summaries and members. Updated mkdocs.yml to enable the macros plugin and set edit_uri. Improved theme palette configuration for better color scheme support. Added mkdocs-macros-plugin to documentation dependencies in pyproject.toml. * Rename 'screenshot' to 'image' in chart docs Updated bar_chart.md, line_chart.md, and pie_chart.md to use the 'image' key instead of 'screenshot' for diagram references and in class_summary calls for consistency. * Rename screenshot argument to image in class_summary macro Refactored the class_summary macro to use 'image' instead of 'screenshot' for clarity and consistency. Updated related variable names and markdown generation accordingly. * Hide Material for MkDocs generator message Added 'generator: false' to the 'extra' section in mkdocs.yml to hide the default 'Made with Material for MkDocs' message from the site footer.
1 parent 789d791 commit ed03795

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

56 files changed

+818
-187
lines changed

‎.github/workflows/docs.yml‎

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

‎README.md‎

Lines changed: 4 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,15 @@ It is based on the [fl_chart](https://pub.dev/packages/fl_chart) Flutter package
1010

1111
## Documentation
1212

13-
Detailed documentation to this package can be found [here](https://flet-dev.github.io/flet-charts/).
13+
Detailed documentation to this package can be found [here](https://flet-charts.docs.flet.dev/).
1414

1515
## Platform Support
1616

1717
This package supports the following platforms:
1818

19-
| Platform | Supported |
20-
|----------|:---------:|
21-
| Windows | ✅ |
22-
| macOS | ✅ |
23-
| Linux | ✅ |
24-
| iOS | ✅ |
25-
| Android | ✅ |
26-
| Web | ✅ |
19+
| Platform | Windows | macOS | Linux | iOS | Android | Web |
20+
|----------|---------|-------|-------|-----|---------|-----|
21+
| Supported| ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
2722

2823
## Usage
2924

@@ -42,11 +37,6 @@ To install the `flet-charts` package and add it to your project dependencies:
4237
```
4338
After this, you will have to manually add this package to your `requirements.txt` or `pyproject.toml`.
4439

45-
- Using `poetry`:
46-
```bash
47-
poetry add flet-charts
48-
```
49-
5040
### Examples
5141

5242
For examples, see [these](./examples).

‎docs/bar_chart.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
---
2+
class_name: flet_charts.bar_chart.BarChart
3+
image: assets/bar-chart-diagram.svg
4+
---
5+
6+
{{ class_summary(class_name, image) }}
7+
18
## Examples
29

310
### Example 1
@@ -20,4 +27,4 @@
2027
--8<-- "examples/charts_example/src/bar_chart/example_2.py"
2128
```
2229

23-
::: flet_charts.bar_chart.BarChart
30+
{{ class_members(class_name) }}

‎docs/bar_chart_group.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
::: flet_charts.bar_chart_group.BarChartGroup
1+
{{ class_all_options("flet_charts.bar_chart_group.BarChartGroup") }}

‎docs/bar_chart_rod.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
::: flet_charts.bar_chart_rod.BarChartRod
1+
{{ class_all_options("flet_charts.bar_chart_rod.BarChartRod") }}

‎docs/bar_chart_rod_stack_item.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
::: flet_charts.bar_chart_rod_stack_item.BarChartRodStackItem
1+
{{ class_all_options("flet_charts.bar_chart_rod_stack_item.BarChartRodStackItem") }}

‎docs/chart_axis.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
::: flet_charts.chart_axis.ChartAxis
1+
{{ class_all_options("flet_charts.chart_axis.ChartAxis") }}

‎docs/chart_axis_label.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
::: flet_charts.chart_axis.ChartAxisLabel
1+
{{ class_all_options("flet_charts.chart_axis.ChartAxisLabel") }}

‎docs/extras/css/mkdocstrings.css‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
/* Material Symbols font with selected icons */
2+
@import url("https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,200,1,200&icon_names=account_tree,bolt,build,category,deployed_code");
3+
4+
/* Hide the original label text */
5+
code.doc-symbol { font-size: 0; }
6+
7+
/* Show only the icon */
8+
code.doc-symbol::before {
9+
font-family: "Material Symbols Outlined";
10+
font-variation-settings: 'FILL' 1, 'GRAD' 200, 'opsz' 24, 'wght' 200;
11+
font-size: .82rem;
12+
position: relative;
13+
top: .25em;
14+
}
15+
16+
.doc-heading .doc-symbol::before {
17+
font-size: 1.0rem;
18+
top: .21em;
19+
}
20+
21+
code.doc-symbol-class::before {
22+
content: "category";
23+
}
24+
25+
code.doc-symbol-attribute::before {
26+
content: "build";
27+
}
28+
29+
code.doc-symbol-event::before {
30+
content: "bolt";
31+
}
32+
33+
code.doc-symbol-method::before {
34+
content: "deployed_code";
35+
}
36+
37+
/* Overrides */
38+
[data-md-color-scheme="default"] {
39+
--doc-symbol-class-fg-color: #f0a502;
40+
--doc-symbol-attribute-fg-color: #0b8dd9; /* ae106f */
41+
--doc-symbol-attribute-bg-color: #9500721a;
42+
43+
--doc-symbol-event-fg-color: #f8aa01;
44+
--doc-symbol-event-bg-color: #e5ff001a;
45+
}
46+
47+
[data-md-color-scheme="slate"] {
48+
--doc-symbol-class-fg-color: #f0a502;
49+
--doc-symbol-attribute-fg-color: #0b8dd9; /* ae106f */
50+
--doc-symbol-attribute-bg-color: #9500721a;
51+
52+
--doc-symbol-event-fg-color: #f8aa01;
53+
--doc-symbol-event-bg-color: #e5ff001a;
54+
}
55+
56+
code.doc-symbol-event,
57+
a code.doc-symbol-event {
58+
color: var(--doc-symbol-event-fg-color);
59+
background-color: var(--doc-symbol-event-bg-color);
60+
}
61+
62+
/* Overrides */
63+
64+
/* Command symbol */
65+
:root, :host,
66+
/* Light mode */
67+
[data-md-color-scheme="default"] {
68+
--doc-symbol-command-fg-color: #9538001;
69+
--doc-symbol-command-bg-color: #9538001a;
70+
}
71+
72+
/* Dark mode */
73+
[data-md-color-scheme="slate"] {
74+
--doc-symbol-command-fg-color: #ffa6571;
75+
--doc-symbol-command-bg-color: #ffa6571a;
76+
}
77+
78+
code.doc-symbol-command,
79+
a code.doc-symbol-command {
80+
color: var(--doc-symbol-command-fg-color);
81+
background-color: var(--doc-symbol-command-bg-color);
82+
}
83+
84+
code.doc-symbol-command::after {
85+
content: "cmd";
86+
}
87+
88+
/* Command symbol */

‎docs/extras/macros/__init__.py‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
def define_env(env):
2+
@env.macro
3+
def class_all_options(class_name, separate_signature=True):
4+
return f"""
5+
::: {class_name}
6+
options:
7+
show_root_toc_entry: true
8+
show_bases: true
9+
separate_signature: {str(separate_signature).lower()}
10+
extra:
11+
show_class_docstring: true
12+
show_children: true
13+
summary:
14+
attributes: true
15+
functions: true
16+
"""
17+
18+
@env.macro
19+
def class_summary(class_name, image=None):
20+
control_name = class_name.split(".")[-1]
21+
image_md = f"\n\n![{control_name}]({image})\n\n" if image else ""
22+
return f"""
23+
::: {class_name}
24+
options:
25+
show_root_toc_entry: true
26+
extra:
27+
show_class_docstring: true
28+
29+
{image_md}
30+
31+
::: {class_name}
32+
options:
33+
show_bases: true
34+
summary:
35+
attributes: true
36+
functions: true
37+
"""
38+
39+
@env.macro
40+
def class_members(class_name):
41+
return f"""
42+
::: {class_name}
43+
options:
44+
extra:
45+
show_children: true
46+
"""

0 commit comments

Comments
 (0)