mr-theme 0.1.1__py3-none-any.whl

mr_theme/__init__.py

@@ -0,0 +1,9 @@
+"""The MR-Theme Package.
+
+.. moduleauthor:: Michael Rippstein <info@anatas.ch>
+
+:copyright: Copyright 2026 by Michael Rippstein.
+:license: MIT, see LICENSE for details.
+"""
+
+from __future__ import annotations

mr_theme/basic_theme/__init__.py

@@ -0,0 +1,39 @@
+"""Basic Sphinx Theme.
+
+.. moduleauthor:: Michael Rippstein <info@anatas.ch>
+
+:copyright: Copyright 2026 by Michael Rippstein.
+:license: MIT, see LICENSE for details.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version as lib_version
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from docutils import nodes
+    from sphinx.application import Sphinx
+
+
+def add_theme_version(
+    app: Sphinx,  # ruff: ignore[unused-function-argument]
+    pagename: str,  # ruff: ignore[unused-function-argument]
+    templatename: str,  # ruff: ignore[unused-function-argument]
+    context: dict[str, Any],
+    doctree: nodes.document,  # ruff: ignore[unused-function-argument]
+) -> None:
+    """Update template names and assets for page build."""
+    # Update version number for the "made with version..." component
+    context['mr_theme_version'] = lib_version('mr_theme')
+
+
+def setup(app: Sphinx) -> None:
+    """Setup the Sphinx application.
+
+    .. codeauthor:: Michael Rippstein <info@anatas.ch>
+    """
+    app.add_html_theme('mr_theme', Path(__file__).resolve().parent)
+
+    app.connect('html-page-context', add_theme_version)

mr_theme/basic_theme/copyright_mr_theme.html

@@ -0,0 +1,27 @@
+{# Displays the copyright information (which is defined in conf.py). #}
+
+{%- macro copyright_block() %}
+  {%- if hasdoc('copyright') %}
+    {%- set copyright_prefix = '<a href="' + pathto('copyright') + '">' + _('Copyright') + '</a>' -%}
+  {%- else %}
+    {%- set copyright_prefix = _('Copyright') %}
+  {%- endif %}
+  {%- if copyright is iterable and copyright is not string %}
+    {% for copyright_line in copyright %}
+      {% trans trimmed copyright_prefix=copyright_prefix, copyright=copyright_line|e %}
+        &#169; {{ copyright_prefix }} {{ copyright }}.
+      {% endtrans %}
+      {%- if not loop.last %}<br />{%- endif %}
+    {% endfor %}
+  {%- else %}
+    {% trans trimmed copyright_prefix=copyright_prefix, copyright=copyright|e %}
+      &#169; {{ copyright_prefix }} {{ copyright }}.
+    {% endtrans %}
+  {%- endif %}
+{%- endmacro %}
+
+{% if show_copyright and copyright %}
+<p class="copyright">
+  {{- copyright_block() -}}
+</p>
+{% endif %}

mr_theme/basic_theme/theme-version-mr-theme.html

@@ -0,0 +1,6 @@
+{# Displays the version of pydata-sphinx-theme used to build the documentation. #}
+<p class="theme-version">
+    Built with <a href="https://gitlab.com/anatas_ch/pyl_mrtheme2">mr-theme</a> {{ mr_theme_version }}<br>
+    based on the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a>
+    {{ theme_version }}.
+</p>

mr_theme/basic_theme/theme.toml

@@ -0,0 +1,13 @@
+# :author: Michael Rippstein <info@anatas.ch>
+# :copyright: Copyright 2026 by Michael Rippstein.
+# :license: MIT, see LICENSE for details.
+
+[theme]
+inherit = "pydata_sphinx_theme"
+
+[options]
+'navbar_center' = ['version', 'navbar-nav']
+'navbar_end' = ['navbar-icon-links']
+'primary_sidebar_end' = ['indices.html', 'sidebar-ethical-ads.html']
+'footer_start' = ['copyright_mr_theme']
+'footer_end' = ['sphinx-version', 'theme-version-mr-theme']

mr_theme/basic_theme/version.html

@@ -0,0 +1,4 @@
+{# This will display the version of the docs #}
+<div class="version-switcher__container version">
+    Version {{ release }}
+</div>

mr_theme/mpl_style/__init__.py

@@ -0,0 +1,390 @@
+"""The MR ``matplotlib`` styles.
+
+.. moduleauthor:: Michael Rippstein <info@anatas.ch>
+
+:copyright: Copyright 2026 by Michael Rippstein.
+:license: MIT, see LICENSE for details.
+
+The «mr_general»-style
+----------------------
+
+.. plot::
+
+    import matplotlib as mpl
+    import matplotlib.pyplot as plt
+    import numpy as np
+
+    import mr_theme.mpl_style
+
+    th = np.linspace(0, 2*np.pi, 128)
+
+    def demo(sty):
+        mpl.style.use(sty)
+        fig, ax = plt.subplots(figsize=(3, 3))
+
+        ax.set_title(f'style: {sty!r}')
+
+        ax.plot(th, np.cos(th), label='C0')
+        ax.plot(th, np.sin(th), label='C1')
+        ax.legend()
+
+
+    demo('default')
+    demo('mr_theme.mpl_style.mr_general')
+
+Colors
+------
+
+.. plot::
+    :include-source: False
+    :caption: The «MR» colors.
+
+    import matplotlib.pyplot as plt
+    from mr_theme.mpl_style import plot_color_table
+
+    plt.style.use('mr_theme.mpl_style.mr_general')
+    fig = plot_color_table(
+        [
+            'mr:brown',
+            'mr:red',
+            'mr:orange',
+            'mr:yellow',
+            'mr:green',
+            'mr:blue',
+            'mr:violet',
+            'mr:gray',
+            'mr:white',
+            'mr:black',
+            'mr:gold',
+            'mr:silver',
+            'mr:pink',
+            'mr:olive',
+            'mr:cyan',
+            'mr:pass',
+            'mr:fail',
+        ],
+        [
+            'mr:brown / mr:bn',
+            'mr:red / mr:rd',
+            'mr:orange / mr:og',
+            'mr:yellow / mr:ye',
+            'mr:green / mr:gn',
+            'mr:blue / mr:bu',
+            'mr:violet / mr:vi',
+            'mr:gray / mr:gy',
+            'mr:white / mr:wh',
+            'mr:black / mr:bk',
+            'mr:gold / mr:gd',
+            'mr:silver / mr:sr',
+            'mr:pink / mr:pk',
+            'mr:olive',
+            'mr:cyan / mr:turquoise / mr:tq',
+            'mr:pass',
+            'mr:fail',
+        ],
+    )
+
+.. plot::
+    :include-source: False
+    :caption: The «MR» colors.
+
+    import matplotlib.pyplot as plt
+
+    from mr_theme.mpl_style import plot_color_table
+
+    plt.style.use('mr_theme.mpl_style.mr_general')
+    fig = plot_color_table(
+        [
+            'mr:prim', 'mr:prim80', 'mr:prim60', 'mr:prim40', 'mr:prim20',
+            'mr:seca', 'mr:seca80', 'mr:seca60', 'mr:seca40', 'mr:seca20',
+            'mr:comp',
+        ],
+        ncols=5,
+    )
+
+.. plot::
+    :include-source: False
+    :caption: The functional color names.
+
+    import matplotlib.pyplot as plt
+    from mr_theme.mpl_style import plot_color_table
+
+    plt.style.use('mr_theme.mpl_style.mr_general')
+    fig = plot_color_table(
+        [
+            'mr:func:bgdark',
+            'mr:func:bglight',
+            'mr:func:grid',
+            'mr:func:text',
+            'mr:func:title'
+        ],
+    )
+
+.. plot::
+    :include-source: False
+    :caption: The default color cycle.
+
+    import matplotlib.pyplot as plt
+    from mr_theme.mpl_style import plot_color_table, DEFAULT_CYCLE_COLORS
+
+    plt.style.use('mr_theme.mpl_style.mr_general')
+    fig = plot_color_table(DEFAULT_CYCLE_COLORS)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any, Literal
+
+import matplotlib as mpl
+from matplotlib import pyplot as plt
+from matplotlib.colors import (  # type: ignore
+    ListedColormap,
+    _colors_full_map,  # ruff: ignore[import-private-name]
+)
+from matplotlib.patches import Rectangle
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from matplotlib.text import Text
+
+MR_COLORS = {
+    'mr:brown': '#8c564b',  # 1
+    'mr:red': '#D62728',  # 2
+    'mr:orange': '#FF7F0E',  # 3
+    'mr:yellow': '#FFF200',  # 4
+    'mr:green': '#2CA02C',  # 5
+    'mr:blue': '#1F77B4',  # 6
+    'mr:violet': '#9467BD',  # 7
+    'mr:gray': '#7f7f7f',  # 8
+    'mr:white': '#e3d9c6',  # 9
+    'mr:black': '#1f1f1f',  # 0
+    'mr:gold': '#FFCE0A',
+    'mr:silver': '#E1E2E3',
+    'mr:pink': '#e377c2',
+    'mr:olive': '#bcbd22',
+    'mr:cyan': '#17becf',
+    'mr:pass': '#1BC237',
+    'mr:fail': '#E31E1E',
+    'mr:prim': '#005083',
+    'mr:prim80': '#33739C',
+    'mr:prim60': '#6696B4',
+    'mr:prim40': '#99B9CD',
+    'mr:prim20': '#CCDCE6',
+    'mr:seca': '#3FB498',
+    'mr:seca80': '#65C3AD',
+    'mr:seca60': '#8BD2C1',
+    'mr:seca40': '#B2E1D6',
+    'mr:seca20': '#D8F0EA',
+    'mr:comp': '#824C00',
+    'mr:func:bgdark': '#333333',
+    'mr:func:bglight': '#F2F2F2',
+    'mr:func:grid': '#808080',
+    'mr:func:text': '#585858',
+}
+MR_COLORS.update({
+    'mr:bn': MR_COLORS['mr:brown'],
+    'mr:rd': MR_COLORS['mr:red'],
+    'mr:og': MR_COLORS['mr:orange'],
+    'mr:ye': MR_COLORS['mr:yellow'],
+    'mr:gn': MR_COLORS['mr:green'],
+    'mr:bu': MR_COLORS['mr:blue'],
+    'mr:vt': MR_COLORS['mr:violet'],
+    'mr:gy': MR_COLORS['mr:gray'],
+    'mr:wh': MR_COLORS['mr:white'],
+    'mr:bk': MR_COLORS['mr:black'],
+    'mr:gd': MR_COLORS['mr:gold'],
+    'mr:sr': MR_COLORS['mr:silver'],
+    'mr:pk': MR_COLORS['mr:pink'],
+    'mr:tq': MR_COLORS['mr:cyan'],
+    'mr:turquoise': MR_COLORS['mr:cyan'],
+    'mr:func:title': MR_COLORS['mr:prim'],
+})
+
+_colors_full_map.update(MR_COLORS)
+
+DEFAULT_CYCLE_COLORS = [
+    'mr:brown',
+    'mr:red',
+    'mr:orange',
+    'mr:yellow',
+    'mr:green',
+    'mr:blue',
+    'mr:violet',
+    'mr:gray',
+    'mr:pink',
+    'mr:olive',
+]
+"""This constant is only for the documentation of the color cycle used by the ``mr_general`` style."""
+
+mr_cmap = ListedColormap(DEFAULT_CYCLE_COLORS, name='mr_cmap')
+mpl.colormaps.register(cmap=mr_cmap)
+
+
+def figure_title(fig: Figure, title: str, **kw_args: Any) -> Text:
+    """Format the figure title according to the style guide.
+
+    .. codeauthor:: Michael Rippstein <info@anatas.ch>
+
+    Parameters
+    ----------
+    fig: matplotlib.figure.Figure
+        A `matplotlib` figure object.
+    title
+        Title of the diagram.
+
+    Returns
+    -------
+    matplotlib.text.Text
+        The `matplotlib` text object.
+
+    Other Parameters
+    ----------------
+    **kw_args
+        Additional `kw_args` are :meth:`~matplotlib.figure.Figure.suptitle` or
+        :class:`~matplotlib.text.Text` properties.
+        The properties ``size`` (``fontsize``), ``weight`` (``fontweight``) and
+        ``color`` (``c``) are not allowed!
+
+    See Also
+    --------
+    matplotlib.figure.Figure.suptitle
+    """
+    return fig.suptitle(title, size='x-large', weight='bold', color='mr:func:title', **kw_args)
+
+
+def axes_ticks_grid(ax: Axes, axis: Literal['both', 'x', 'y'] = 'both') -> None:
+    """Switch on the minorticks and format the minor grid lines.
+
+    .. codeauthor:: Michael Rippstein <info@anatas.ch>
+
+    Parameters
+    ----------
+    ax : matplotlib.axes.Axes
+        The axes object
+    axis
+        On which axis the minor grid is draw, by default on both.
+    """
+    ax.minorticks_on()
+    ax.grid(visible=True, which='both', axis=axis)
+    ax.grid(which='minor', axis=axis, linestyle=':')
+
+
+def plot_color_table(  # ruff: ignore[too-many-locals]
+    colors: list[str], labels: list[str] | None = None, *, ncols: int = 4, **kw_args: int
+) -> Figure:
+    """Plot color table for the documentation.
+
+    .. codeauthor:: Michael Rippstein <info@anatas.ch>
+
+    Parameters
+    ----------
+    colors
+        A list of valid colors name.
+    labels
+        A list of labels to name the colors. The list must have the same length as the `colors` list.
+        By default the strings in the `colors` list is used to print the colors name.
+    ncols
+        The number of columns, by default 4.
+
+    Keyword Arguments
+    -----------------
+    cell_width : int
+        The width of one cell, by default 240 pixel.
+    cell_height : int
+        The height of one cell, by default 22 pixel.
+    swatch_width : int
+        The width of the colour swatch, by default 48 pixel.
+    swatch_height : int
+        The height of the colour swatch, by default 18 pixel.
+        Must by a even number smaller than the `cell_height`.
+    margin : int
+        The margin around the table, by default 12 pixel.
+    dpi : int
+        The dpi of the image, by default 96.
+    fontsize : int
+        The fontsize, by default 14 pixel.
+        Must by a even number smaller than the `cell_height`.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        A matplotlib figure object.
+    """
+    if labels is None:
+        labels = colors
+    cell_width = kw_args.get('cell_width', 240)
+    cell_height = kw_args.get('cell_height', 22)
+    swatch_width = kw_args.get('swatch_width', 48)
+    swatch_height = kw_args.get('swatch_height', 18)
+    margin = kw_args.get('margin', 12)
+    dpi = kw_args.get('dpi', 96)
+    fontsize = kw_args.get('fontsize', 14)
+    n = len(colors)
+    nrows = math.ceil(n / ncols)
+    width = cell_width * ncols + 2 * margin
+    height = cell_height * nrows + 2 * margin
+    fig, ax = plt.subplots(figsize=(width / dpi, height / dpi), dpi=dpi)
+    fig.subplots_adjust(
+        margin / width,
+        margin / height,
+        (width - margin) / width,
+        (height - margin) / height,
+    )
+    ax.set_xlim(0, cell_width * ncols)
+    ax.set_ylim(cell_height * (nrows - 0.5), -cell_height / 2.0)
+    ax.yaxis.set_visible(False)
+    ax.xaxis.set_visible(False)
+    ax.set_axis_off()
+    for i, (name, label) in enumerate(zip(colors, labels, strict=True)):
+        row = i % nrows
+        col = i // nrows
+        y = row * cell_height
+        swatch_start_x = cell_width * col
+        text_pos_x = cell_width * col + swatch_width + fontsize // 2
+        ax.text(
+            text_pos_x,
+            y,
+            label,
+            fontsize=fontsize,
+            horizontalalignment='left',
+            verticalalignment='center',
+        )
+        ax.add_patch(
+            Rectangle(
+                xy=(swatch_start_x, y - swatch_height // 2),
+                width=swatch_width,
+                height=swatch_height,
+                facecolor=name,
+                edgecolor='0.7',
+            )
+        )
+    return fig
+
+
+def fig_text_info_note(fig: Figure, text: str) -> Text:
+    """Print a text in the bottom right corner of a `matplotlib` figure.
+
+    .. codeauthor:: Michael Rippstein <info@anatas.ch>
+
+    Parameters
+    ----------
+    fig: matplotlib.figure.Figure
+        A `matplotlib` figure object.
+    text
+        serial number
+
+    Returns
+    -------
+    matplotlib.text.Text
+        The `matplotlib` text object.
+    """
+    return fig.text(
+        0.99,
+        0.01,
+        text,
+        color='mr:func:text',
+        verticalalignment='bottom',
+        horizontalalignment='right',
+    )