Skip to content

Commit 5aa0922

Browse files
lord-haffilord-haffi
authored
docs: Improve readablity and styling of the compatibility matrix' legend (#1016)
This also shows how to customize styling which may be helpful for later customizations.
1 parent 64af903 commit 5aa0922

5 files changed

Lines changed: 56 additions & 25 deletions

File tree

‎.gitignore‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -166,8 +166,8 @@ Temporary Items
166166
# This directory rebuilds on 'tox -e docs' therefore not needed in repo
167167
docs/api
168168
docs/plantuml.jar
169-
docs/_static
170-
docs/compatibility_matrix.csv
169+
docs/_static/images
170+
docs/_static/tables
171171

172172
# version number for bo4e-python; gets auto-generated during the command
173173
# python -m build

‎docs/_static/css/colors.css‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
2+
:root {
3+
/* These colors should stay consistent with the colors used in the CLI:
4+
https://github.com/bo4e/BO4E-CLI/blob/main/src/bo4e_cli/io/console/style.py#L238 */
5+
--main-color: #8cc04d;
6+
--sub-color: #617d8b;
7+
--error-color: #e35b3a;
8+
}
9+
10+
.main-color {
11+
color: var(--main-color);
12+
}
13+
.sub-color {
14+
color: var(--sub-color);
15+
}
16+
.error-color {
17+
color: var(--error-color);
18+
}

‎docs/_static/css/override.css‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
2+
.rst-content table .line-block:last-child {
3+
/* Remove the margin-bottom from the line-blocks inside tables. Example in changelog.rst. */
4+
margin-bottom: 0;
5+
}

‎docs/changelog.rst‎

Lines changed: 21 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,29 +20,27 @@ You can also download the compatibility matrix as CSV file `here <_static/tables
2020
.. table:: Legend for compatibility matrix
2121
:widths: 10 90
2222

23-
+------+------------------------------------------------------+
24-
| Icon | Description |
25-
+======+======================================================+
26-
| 🟢 | Compatible |
27-
| | No changes in the data model |
28-
+------+------------------------------------------------------+
29-
| 🟡 | Compatible |
30-
| | Only non-critical changes in the data model |
31-
| | e.g. added fields, changed doc strings |
32-
+------+------------------------------------------------------+
33-
| 🔴 | Incompatible |
34-
| | Critical changes in the data model |
35-
| | e.g. removed fields, changed types |
36-
+------+------------------------------------------------------+
37-
| ➕ | Compatible |
38-
| | Data model was added in this version |
39-
+------+------------------------------------------------------+
40-
| ➖ | Incompatible |
41-
| | Data model was removed in this version |
42-
+------+------------------------------------------------------+
43-
| \- | Data model not existent in this version |
44-
| | was removed before or will be added in future |
45-
+------+------------------------------------------------------+
23+
+------+---------------------------------------------------------------------------------------------------+
24+
| Icon | Description |
25+
+======+===================================================================================================+
26+
| 🟢 | | :main-color:`Compatible` |
27+
| | | No changes in the data model |
28+
+------+---------------------------------------------------------------------------------------------------+
29+
| 🟡 | | :main-color:`Compatible` |
30+
| | | Only non\-critical changes in the data model e.g. added fields, changed doc strings |
31+
+------+---------------------------------------------------------------------------------------------------+
32+
| 🔴 | | :error-color:`Incompatible` |
33+
| | | Critical changes in the data model e.g. removed fields, changed types |
34+
+------+---------------------------------------------------------------------------------------------------+
35+
| ➕ | | :main-color:`Compatible` |
36+
| | | Data model was added in this version |
37+
+------+---------------------------------------------------------------------------------------------------+
38+
| ➖ | | :error-color:`Incompatible` |
39+
| | | Data model was removed in this version |
40+
+------+---------------------------------------------------------------------------------------------------+
41+
| \- | | Non\-existent |
42+
| | | Doesn't exist in this version i.e. it was removed before or will be added in future |
43+
+------+---------------------------------------------------------------------------------------------------+
4644

4745
.. csv-table:: Compatibility matrix
4846
:file: _static/tables/compatibility_matrix.csv

‎docs/conf.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,16 @@ def setup(app):
196196
"titles_only": False,
197197
}
198198

199+
html_css_files = [
200+
"css/override.css",
201+
"css/colors.css",
202+
]
203+
rst_prolog = """
204+
.. role:: main-color
205+
.. role:: sub-color
206+
.. role:: error-color
207+
"""
208+
199209
# Add any paths that contain custom themes here, relative to this directory.
200210
# html_theme_path = []
201211

0 commit comments

Comments
 (0)